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 .
![[BACK]](/icons//back.gif){kind=icon}
Return to fopen.3 CVS log ![[TXT]](/icons//text.gif){kind=icon}
![[DIR]](/icons//dir.gif){kind=icon}
Up to [DragonFly] / src / lib / libc / stdio