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

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 $
1.2     ! dillon     38: .\" $DragonFly: src/lib/libc/stdio/fopen.3,v 1.1 2003/06/16 04:33:23 dillon Exp $
1.1       dillon     39: .\"
                     40: .Dd June 4, 1993
                     41: .Dt FOPEN 3
                     42: .Os
                     43: .Sh NAME
                     44: .Nm fopen ,
                     45: .Nm fdopen ,
                     46: .Nm freopen
                     47: .Nd stream open functions
                     48: .Sh LIBRARY
                     49: .Lb libc
                     50: .Sh SYNOPSIS
                     51: .In stdio.h
                     52: .Ft FILE *
                     53: .Fn fopen "const char *path" "const char *mode"
                     54: .Ft FILE *
                     55: .Fn fdopen "int fildes" "const char *mode"
                     56: .Ft FILE *
                     57: .Fn freopen "const char *path" "const char *mode" "FILE *stream"
                     58: .Sh DESCRIPTION
                     59: The
                     60: .Fn fopen
                     61: function
                     62: opens the file whose name is the string pointed to by
                     63: .Fa path
                     64: and associates a stream with it.
                     65: .Pp
                     66: The argument
                     67: .Fa mode
                     68: points to a string beginning with one of the following
                     69: sequences (Additional characters may follow these sequences.):
                     70: .Bl -tag -width indent
                     71: .It Dq Li r
                     72: Open text file for reading.
                     73: The stream is positioned at the beginning of the file.
                     74: .It Dq Li r+
                     75: Open for reading and writing.
                     76: The stream is positioned at the beginning of the file.
                     77: .It Dq Li w
                     78: Truncate file to zero length or create text file for writing.
                     79: The stream is positioned at the beginning of the file.
                     80: .It Dq Li w+
                     81: Open for reading and writing.
                     82: The file is created if it does not exist, otherwise it is truncated.
                     83: The stream is positioned at the beginning of the file.
                     84: .It Dq Li a
                     85: Open for writing.
                     86: The file is created if it does not exist.
                     87: The stream is positioned at the end of the file.
                     88: Subsequent writes to the file will always end up at the then current
                     89: end of file, irrespective of any intervening
                     90: .Xr fseek 3
                     91: or similar.
                     92: .It Dq Li a+
                     93: Open for reading and writing.
                     94: The file is created if it does not exist.
                     95: The stream is positioned at the end of the file.
                     96: Subsequent writes to the file will always end up at the then current
                     97: end of file, irrespective of any intervening
                     98: .Xr fseek 3
                     99: or similar.
                    100: .El
                    101: .Pp
                    102: The
                    103: .Fa mode
                    104: string can also include the letter ``b'' either as a third character or
                    105: as a character between the characters in any of the two-character strings
                    106: described above.
                    107: This is strictly for compatibility with
                    108: .St -isoC
                    109: and has no effect; the ``b'' is ignored.
                    110: .Pp
                    111: Any created files will have mode
                    112: .Pf \\*q Dv S_IRUSR
                    113: \&|
                    114: .Dv S_IWUSR
                    115: \&|
                    116: .Dv S_IRGRP
                    117: \&|
                    118: .Dv S_IWGRP
                    119: \&|
                    120: .Dv S_IROTH
                    121: \&|
                    122: .Dv S_IWOTH Ns \\*q
                    123: .Pq Li 0666 ,
                    124: as modified by the process'
                    125: umask value (see
                    126: .Xr umask 2 ) .
                    127: .Pp
                    128: Reads and writes may be intermixed on read/write streams in any order,
                    129: and do not require an intermediate seek as in previous versions of
                    130: .Em stdio .
                    131: This is not portable to other systems, however;
                    132: .Tn ANSI C
                    133: requires that
                    134: a file positioning function intervene between output and input, unless
                    135: an input operation encounters end-of-file.
                    136: .Pp
                    137: The
                    138: .Fn fdopen
                    139: function associates a stream with the existing file descriptor,
                    140: .Fa fildes .
                    141: The
                    142: .Fa mode
                    143: of the stream must be compatible with the mode of the file descriptor.
                    144: When the stream is closed via
                    145: .Xr fclose 3 ,
                    146: .Fa fildes
                    147: is closed also.
                    148: .Pp
                    149: The
                    150: .Fn freopen
                    151: function
                    152: opens the file whose name is the string pointed to by
                    153: .Fa path
                    154: and associates the stream pointed to by
                    155: .Fa stream
                    156: with it.
                    157: The original stream (if it exists) is closed.
                    158: The
                    159: .Fa mode
                    160: argument is used just as in the
                    161: .Fn fopen
                    162: function.
                    163: The primary use of the
                    164: .Fn freopen
                    165: function
                    166: is to change the file associated with a
                    167: standard text stream
                    168: .Pf ( Em stderr ,
                    169: .Em stdin ,
                    170: or
                    171: .Em stdout ) .
                    172: .Sh RETURN VALUES
                    173: Upon successful completion
                    174: .Fn fopen ,
                    175: .Fn fdopen
                    176: and
                    177: .Fn freopen
                    178: return a
                    179: .Tn FILE
                    180: pointer.
                    181: Otherwise,
                    182: .Dv NULL
                    183: is returned and the global variable
                    184: .Va errno
                    185: is set to indicate the error.
                    186: .Sh ERRORS
                    187: .Bl -tag -width Er
                    188: .It Bq Er EINVAL
                    189: The
                    190: .Fa mode
                    191: provided to
                    192: .Fn fopen ,
                    193: .Fn fdopen ,
                    194: or
                    195: .Fn freopen
                    196: was invalid.
                    197: .El
                    198: .Pp
                    199: The
                    200: .Fn fopen ,
                    201: .Fn fdopen
                    202: and
                    203: .Fn freopen
                    204: functions
                    205: may also fail and set
                    206: .Va errno
                    207: for any of the errors specified for the routine
                    208: .Xr malloc 3 .
                    209: .Pp
                    210: The
                    211: .Fn fopen
                    212: function
                    213: may also fail and set
                    214: .Va errno
                    215: for any of the errors specified for the routine
                    216: .Xr open 2 .
                    217: .Pp
                    218: The
                    219: .Fn fdopen
                    220: function
                    221: may also fail and set
                    222: .Va errno
                    223: for any of the errors specified for the routine
                    224: .Xr fcntl 2 .
                    225: .Pp
                    226: The
                    227: .Fn freopen
                    228: function
                    229: may also fail and set
                    230: .Va errno
                    231: for any of the errors specified for the routines
                    232: .Xr open 2 ,
                    233: .Xr fclose 3
                    234: and
                    235: .Xr fflush 3 .
                    236: .Sh SEE ALSO
                    237: .Xr open 2 ,
                    238: .Xr fclose 3 ,
                    239: .Xr fileno 3 ,
                    240: .Xr fseek 3 ,
                    241: .Xr funopen 3
                    242: .Sh STANDARDS
                    243: The
                    244: .Fn fopen
                    245: and
                    246: .Fn freopen
                    247: functions
                    248: conform to
                    249: .St -isoC .
                    250: The
                    251: .Fn fdopen
                    252: function
                    253: conforms to
                    254: .St -p1003.1-88 .