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

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.3       hmp        38: .\" $DragonFly$
1.1       dillon     39: .\"
1.4     ! swildner   40: .Dd June 8, 2004
1.1       dillon     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 .
1.3       hmp       141: The mode
1.1       dillon    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.
1.3       hmp       162: .Pp
                    163: If the
                    164: .Fa path
                    165: argument is
                    166: .Dv NULL ,
                    167: .Fn freopen
                    168: attempts to re-open the file associated with
                    169: .Fa stream
                    170: with a new mode.
                    171: The new mode must be compatible with the mode that the stream was originally
                    172: opened with:
                    173: .Bl -bullet -offset indent
                    174: .It
                    175: Streams originally opened with mode
                    176: .Dq Li r
                    177: can only be reopened with that same mode.
                    178: .It
                    179: Streams originally opened with mode
                    180: .Dq Li a
                    181: can be reopened with the same mode, or mode
                    182: .Dq Li w .
                    183: .It
                    184: Streams originally opened with mode
                    185: .Dq Li w
                    186: can be reopened with the same mode, or mode
                    187: .Dq Li a .
                    188: .It
                    189: Streams originally opened with mode
                    190: .Dq Li r+ ,
                    191: .Dq Li w+ ,
                    192: or
                    193: .Dq Li a+
                    194: can be reopened with any mode.
                    195: .El
                    196: .Pp
1.1       dillon    197: The primary use of the
                    198: .Fn freopen
                    199: function
                    200: is to change the file associated with a
                    201: standard text stream
1.3       hmp       202: .Dv ( stderr , stdin ,
1.1       dillon    203: or
1.3       hmp       204: .Dv stdout ) .
1.1       dillon    205: .Sh RETURN VALUES
                    206: Upon successful completion
                    207: .Fn fopen ,
                    208: .Fn fdopen
                    209: and
                    210: .Fn freopen
                    211: return a
                    212: .Tn FILE
                    213: pointer.
                    214: Otherwise,
                    215: .Dv NULL
                    216: is returned and the global variable
                    217: .Va errno
                    218: is set to indicate the error.
                    219: .Sh ERRORS
                    220: .Bl -tag -width Er
                    221: .It Bq Er EINVAL
                    222: The
                    223: .Fa mode
1.3       hmp       224: argument
                    225: to
1.1       dillon    226: .Fn fopen ,
                    227: .Fn fdopen ,
                    228: or
                    229: .Fn freopen
                    230: was invalid.
                    231: .El
                    232: .Pp
                    233: The
                    234: .Fn fopen ,
                    235: .Fn fdopen
                    236: and
                    237: .Fn freopen
                    238: functions
                    239: may also fail and set
                    240: .Va errno
                    241: for any of the errors specified for the routine
                    242: .Xr malloc 3 .
                    243: .Pp
                    244: The
                    245: .Fn fopen
                    246: function
                    247: may also fail and set
                    248: .Va errno
                    249: for any of the errors specified for the routine
                    250: .Xr open 2 .
                    251: .Pp
                    252: The
                    253: .Fn fdopen
                    254: function
                    255: may also fail and set
                    256: .Va errno
                    257: for any of the errors specified for the routine
                    258: .Xr fcntl 2 .
                    259: .Pp
                    260: The
                    261: .Fn freopen
                    262: function
                    263: may also fail and set
                    264: .Va errno
                    265: for any of the errors specified for the routines
                    266: .Xr open 2 ,
                    267: .Xr fclose 3
                    268: and
                    269: .Xr fflush 3 .
                    270: .Sh SEE ALSO
                    271: .Xr open 2 ,
                    272: .Xr fclose 3 ,
                    273: .Xr fileno 3 ,
                    274: .Xr fseek 3 ,
                    275: .Xr funopen 3
                    276: .Sh STANDARDS
                    277: The
                    278: .Fn fopen
                    279: and
                    280: .Fn freopen
                    281: functions
                    282: conform to
                    283: .St -isoC .
                    284: The
                    285: .Fn fdopen
                    286: function
                    287: conforms to
                    288: .St -p1003.1-88 .