Annotation of src/lib/libc/stdio/fopen.3, revision 1.3
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.3 ! hmp 40: .Dd June 08, 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 .
![[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