Annotation of src/lib/libc/stdio/fopen.3, revision 1.1

1.1     ! dillon      1: .\" Copyright (c) 1990, 1991, 1993
        !             2: .\"    The Regents of the University of California.  All rights reserved.
        !             3: .\"
        !             4: .\" This code is derived from software contributed to Berkeley by
        !             5: .\" Chris Torek and the American National Standards Committee X3,
        !             6: .\" on Information Processing Systems.
        !             7: .\"
        !             8: .\" Redistribution and use in source and binary forms, with or without
        !             9: .\" modification, are permitted provided that the following conditions
        !            10: .\" are met:
        !            11: .\" 1. Redistributions of source code must retain the above copyright
        !            12: .\"    notice, this list of conditions and the following disclaimer.
        !            13: .\" 2. Redistributions in binary form must reproduce the above copyright
        !            14: .\"    notice, this list of conditions and the following disclaimer in the
        !            15: .\"    documentation and/or other materials provided with the distribution.
        !            16: .\" 3. All advertising materials mentioning features or use of this software
        !            17: .\"    must display the following acknowledgement:
        !            18: .\"    This product includes software developed by the University of
        !            19: .\"    California, Berkeley and its contributors.
        !            20: .\" 4. Neither the name of the University nor the names of its contributors
        !            21: .\"    may be used to endorse or promote products derived from this software
        !            22: .\"    without specific prior written permission.
        !            23: .\"
        !            24: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
        !            25: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        !            26: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
        !            27: .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
        !            28: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        !            29: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
        !            30: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
        !            31: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
        !            32: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
        !            33: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
        !            34: .\" SUCH DAMAGE.
        !            35: .\"
        !            36: .\"     @(#)fopen.3    8.1 (Berkeley) 6/4/93
        !            37: .\" $FreeBSD: src/lib/libc/stdio/fopen.3,v 1.7.2.6 2001/12/14 18:33:57 ru Exp $
        !            38: .\"
        !            39: .Dd June 4, 1993
        !            40: .Dt FOPEN 3
        !            41: .Os
        !            42: .Sh NAME
        !            43: .Nm fopen ,
        !            44: .Nm fdopen ,
        !            45: .Nm freopen
        !            46: .Nd stream open functions
        !            47: .Sh LIBRARY
        !            48: .Lb libc
        !            49: .Sh SYNOPSIS
        !            50: .In stdio.h
        !            51: .Ft FILE *
        !            52: .Fn fopen "const char *path" "const char *mode"
        !            53: .Ft FILE *
        !            54: .Fn fdopen "int fildes" "const char *mode"
        !            55: .Ft FILE *
        !            56: .Fn freopen "const char *path" "const char *mode" "FILE *stream"
        !            57: .Sh DESCRIPTION
        !            58: The
        !            59: .Fn fopen
        !            60: function
        !            61: opens the file whose name is the string pointed to by
        !            62: .Fa path
        !            63: and associates a stream with it.
        !            64: .Pp
        !            65: The argument
        !            66: .Fa mode
        !            67: points to a string beginning with one of the following
        !            68: sequences (Additional characters may follow these sequences.):
        !            69: .Bl -tag -width indent
        !            70: .It Dq Li r
        !            71: Open text file for reading.
        !            72: The stream is positioned at the beginning of the file.
        !            73: .It Dq Li r+
        !            74: Open for reading and writing.
        !            75: The stream is positioned at the beginning of the file.
        !            76: .It Dq Li w
        !            77: Truncate file to zero length or create text file for writing.
        !            78: The stream is positioned at the beginning of the file.
        !            79: .It Dq Li w+
        !            80: Open for reading and writing.
        !            81: The file is created if it does not exist, otherwise it is truncated.
        !            82: The stream is positioned at the beginning of the file.
        !            83: .It Dq Li a
        !            84: Open for writing.
        !            85: The file is created if it does not exist.
        !            86: The stream is positioned at the end of the file.
        !            87: Subsequent writes to the file will always end up at the then current
        !            88: end of file, irrespective of any intervening
        !            89: .Xr fseek 3
        !            90: or similar.
        !            91: .It Dq Li a+
        !            92: Open for reading and writing.
        !            93: The file is created if it does not exist.
        !            94: The stream is positioned at the end of the file.
        !            95: Subsequent writes to the file will always end up at the then current
        !            96: end of file, irrespective of any intervening
        !            97: .Xr fseek 3
        !            98: or similar.
        !            99: .El
        !           100: .Pp
        !           101: The
        !           102: .Fa mode
        !           103: string can also include the letter ``b'' either as a third character or
        !           104: as a character between the characters in any of the two-character strings
        !           105: described above.
        !           106: This is strictly for compatibility with
        !           107: .St -isoC
        !           108: and has no effect; the ``b'' is ignored.
        !           109: .Pp
        !           110: Any created files will have mode
        !           111: .Pf \\*q Dv S_IRUSR
        !           112: \&|
        !           113: .Dv S_IWUSR
        !           114: \&|
        !           115: .Dv S_IRGRP
        !           116: \&|
        !           117: .Dv S_IWGRP
        !           118: \&|
        !           119: .Dv S_IROTH
        !           120: \&|
        !           121: .Dv S_IWOTH Ns \\*q
        !           122: .Pq Li 0666 ,
        !           123: as modified by the process'
        !           124: umask value (see
        !           125: .Xr umask 2 ) .
        !           126: .Pp
        !           127: Reads and writes may be intermixed on read/write streams in any order,
        !           128: and do not require an intermediate seek as in previous versions of
        !           129: .Em stdio .
        !           130: This is not portable to other systems, however;
        !           131: .Tn ANSI C
        !           132: requires that
        !           133: a file positioning function intervene between output and input, unless
        !           134: an input operation encounters end-of-file.
        !           135: .Pp
        !           136: The
        !           137: .Fn fdopen
        !           138: function associates a stream with the existing file descriptor,
        !           139: .Fa fildes .
        !           140: The
        !           141: .Fa mode
        !           142: of the stream must be compatible with the mode of the file descriptor.
        !           143: When the stream is closed via
        !           144: .Xr fclose 3 ,
        !           145: .Fa fildes
        !           146: is closed also.
        !           147: .Pp
        !           148: The
        !           149: .Fn freopen
        !           150: function
        !           151: opens the file whose name is the string pointed to by
        !           152: .Fa path
        !           153: and associates the stream pointed to by
        !           154: .Fa stream
        !           155: with it.
        !           156: The original stream (if it exists) is closed.
        !           157: The
        !           158: .Fa mode
        !           159: argument is used just as in the
        !           160: .Fn fopen
        !           161: function.
        !           162: The primary use of the
        !           163: .Fn freopen
        !           164: function
        !           165: is to change the file associated with a
        !           166: standard text stream
        !           167: .Pf ( Em stderr ,
        !           168: .Em stdin ,
        !           169: or
        !           170: .Em stdout ) .
        !           171: .Sh RETURN VALUES
        !           172: Upon successful completion
        !           173: .Fn fopen ,
        !           174: .Fn fdopen
        !           175: and
        !           176: .Fn freopen
        !           177: return a
        !           178: .Tn FILE
        !           179: pointer.
        !           180: Otherwise,
        !           181: .Dv NULL
        !           182: is returned and the global variable
        !           183: .Va errno
        !           184: is set to indicate the error.
        !           185: .Sh ERRORS
        !           186: .Bl -tag -width Er
        !           187: .It Bq Er EINVAL
        !           188: The
        !           189: .Fa mode
        !           190: provided to
        !           191: .Fn fopen ,
        !           192: .Fn fdopen ,
        !           193: or
        !           194: .Fn freopen
        !           195: was invalid.
        !           196: .El
        !           197: .Pp
        !           198: The
        !           199: .Fn fopen ,
        !           200: .Fn fdopen
        !           201: and
        !           202: .Fn freopen
        !           203: functions
        !           204: may also fail and set
        !           205: .Va errno
        !           206: for any of the errors specified for the routine
        !           207: .Xr malloc 3 .
        !           208: .Pp
        !           209: The
        !           210: .Fn fopen
        !           211: function
        !           212: may also fail and set
        !           213: .Va errno
        !           214: for any of the errors specified for the routine
        !           215: .Xr open 2 .
        !           216: .Pp
        !           217: The
        !           218: .Fn fdopen
        !           219: function
        !           220: may also fail and set
        !           221: .Va errno
        !           222: for any of the errors specified for the routine
        !           223: .Xr fcntl 2 .
        !           224: .Pp
        !           225: The
        !           226: .Fn freopen
        !           227: function
        !           228: may also fail and set
        !           229: .Va errno
        !           230: for any of the errors specified for the routines
        !           231: .Xr open 2 ,
        !           232: .Xr fclose 3
        !           233: and
        !           234: .Xr fflush 3 .
        !           235: .Sh SEE ALSO
        !           236: .Xr open 2 ,
        !           237: .Xr fclose 3 ,
        !           238: .Xr fileno 3 ,
        !           239: .Xr fseek 3 ,
        !           240: .Xr funopen 3
        !           241: .Sh STANDARDS
        !           242: The
        !           243: .Fn fopen
        !           244: and
        !           245: .Fn freopen
        !           246: functions
        !           247: conform to
        !           248: .St -isoC .
        !           249: The
        !           250: .Fn fdopen
        !           251: function
        !           252: conforms to
        !           253: .St -p1003.1-88 .