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 .
![[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