| blob | ec6db64356ae12be446d6bc343b731329ce23d04 |
1 .\" $NetBSD: fopen.3,v 1.28 2012/07/02 20:02:43 wiz Exp $
2 .\"
3 .\" Copyright (c) 1990, 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" This code is derived from software contributed to Berkeley by
7 .\" Chris Torek and the American National Standards Committee X3,
8 .\" on Information Processing Systems.
9 .\"
10 .\" Redistribution and use in source and binary forms, with or without
11 .\" modification, are permitted provided that the following conditions
12 .\" are met:
13 .\" 1. Redistributions of source code must retain the above copyright
14 .\" notice, this list of conditions and the following disclaimer.
15 .\" 2. Redistributions in binary form must reproduce the above copyright
16 .\" notice, this list of conditions and the following disclaimer in the
17 .\" documentation and/or other materials provided with the distribution.
18 .\" 3. Neither the name of the University nor the names of its contributors
19 .\" may be used to endorse or promote products derived from this software
20 .\" without specific prior written permission.
21 .\"
22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .\" SUCH DAMAGE.
33 .\"
34 .\" @(#)fopen.3 8.1 (Berkeley) 6/4/93
35 .\"
36 .Dd July 18, 2011
37 .Dt FOPEN 3
38 .Os
39 .Sh NAME
40 .Nm fopen ,
41 .Nm fdopen ,
42 .Nm freopen
43 .Nd stream open functions
44 .Sh LIBRARY
45 .Lb libc
46 .Sh SYNOPSIS
47 .In stdio.h
48 .Ft FILE *
49 .Fn fopen "const char * restrict path" "const char * restrict mode"
50 .Ft FILE *
51 .Fn fdopen "int fildes" "const char *mode"
52 .Ft FILE *
53 .Fn freopen "const char * restrict path" "const char * restrict mode" "FILE * restrict stream"
54 .Sh DESCRIPTION
55 The
56 .Fn fopen
57 function
58 opens the file whose name is the string pointed to by
59 .Fa path
60 and associates a stream with it.
61 .Pp
62 The argument
63 .Fa mode
64 points to a string beginning with one of the following
65 sequences (Additional characters may follow these sequences.):
66 .Bl -tag -width 4n
67 .It Dq Li a
68 Append; open for writing.
69 The file is created if it does not exist.
70 .It Dq Li a+
71 Append; open for reading and writing.
72 The file is created if it does not exist.
73 .It Dq Li r
74 Open for reading.
75 .It Dq Li r+
76 Open for reading and writing.
77 .It Dq Li w
78 Open for writing.
79 Truncate file to zero length or create file.
80 .It Dq Li w+
81 Open for reading and writing.
82 Truncate file to zero length or create file.
83 .El
84 .Pp
85 Additionally, the
86 .Fa mode
87 string can also include one of the following letters:
88 .Bl -tag -width 4n
89 .It Sq b
90 The letter
91 .Sq b
92 may appear either as a last character or as a character between the
93 characters in any of the two-character strings described above.
94 This is strictly for compatibility with
95 .St -ansiC
96 and has no effect; the
97 .Sq b
98 is ignored.
99 .It Sq e
100 The letter
101 .Sq e
102 in the mode string sets the close-on-exec flag in the file descriptors of
103 the newly opened file files; if the operation fails,
104 .Fn fopen
105 will fail.
106 This is a non
107 .St -ansiC
108 extension.
109 .It Sq f
110 The letter
111 .Sq f
112 in the mode string restricts
113 .Fn fopen
114 to regular files; if the file opened is not a regular file,
115 .Fn fopen
116 will fail.
117 This is a non
118 .St -ansiC
119 extension.
120 .El
121 .Pp
122 Any created files will have mode
123 .Pf \*q Dv S_IRUSR
124 \&|
125 .Dv S_IWUSR
126 \&|
127 .Dv S_IRGRP
128 \&|
129 .Dv S_IWGRP
130 \&|
131 .Dv S_IROTH
132 \&|
133 .Dv S_IWOTH Ns \*q
134 .Pq Li 0666 ,
135 as modified by the process'
136 .Xr umask 2
137 value.
138 .Pp
139 Opening a file with append mode causes all subsequent writes to it
140 to be forced to the then current end of file, regardless of intervening
141 repositioning of the stream.
142 .Pp
143 The
144 .Fn fopen
145 and
146 .Fn freopen
147 functions initially position the stream at the start of the file
148 unless the file is opened with append mode,
149 in which case the stream is initially positioned at the end of the file.
150 .\" PR 6072 claims this paragraph is not correct.
151 .\" .Pp
152 .\" Reads and writes may be intermixed on read/write streams in any order,
153 .\" and do not require an intermediate seek as in previous versions of
154 .\" .Em stdio .
155 .\" This is not portable to other systems, however;
156 .\" .Tn ANSI C
157 .\" requires that
158 .\" a file positioning function intervene between output and input, unless
159 .\" an input operation encounters end-of-file.
160 .Pp
161 The
162 .Fn fdopen
163 function associates a stream with the existing file descriptor,
164 .Fa fildes .
165 The
166 .Fa mode
167 of the stream must be compatible with the mode of the file descriptor.
168 The stream is positioned at the file offset of the file descriptor.
169 .Pp
170 The
171 .Fn freopen
172 function
173 opens the file whose name is the string pointed to by
174 .Fa path
175 and associates the stream pointed to by
176 .Fa stream
177 with it.
178 The original stream (if it exists) is closed.
179 The
180 .Fa mode
181 argument is used just as in the
182 .Fn fopen
183 function.
184 The primary use of the
185 .Fn freopen
186 function
187 is to change the file associated with a
188 standard text stream
189 .Pf ( Em stderr ,
190 .Em stdin ,
191 or
192 .Em stdout ) .
193 .Sh RETURN VALUES
194 Upon successful completion
195 .Fn fopen ,
196 .Fn fdopen
197 and
198 .Fn freopen
199 return a
200 .Tn FILE
201 pointer.
202 Otherwise,
203 .Dv NULL
204 is returned and the global variable
205 .Va errno
206 is set to indicate the error.
207 .Sh ERRORS
208 The functions may fail if:
209 .Bl -tag -width Er
210 .It Bq Er EFTYPE
211 The file is not a regular file and the character ``f'' is specified
212 in the mode.
213 .It Bq Er EINVAL
214 The specified
215 .Fa mode
216 was invalid.
217 .El
218 .Pp
219 The
220 .Fn fopen ,
221 .Fn fdopen
222 and
223 .Fn freopen
224 functions
225 may also fail and set
226 .Va errno
227 for any of the errors specified for the routine
228 .Xr malloc 3 .
229 .Pp
230 The
231 .Fn fopen
232 function
233 may also fail and set
234 .Va errno
235 for any of the errors specified for the routine
236 .Xr open 2 .
237 .Pp
238 The
239 .Fn fdopen
240 function
241 may also fail and set
242 .Va errno
243 for any of the errors specified for the routine
244 .Xr fcntl 2 .
245 .Pp
246 The
247 .Fn freopen
248 function
249 may also fail and set
250 .Va errno
251 for any of the errors specified for the routines
252 .Xr open 2 ,
253 .Xr fclose 3
254 and
255 .Xr fflush 3 .
256 .Sh SEE ALSO
257 .Xr open 2 ,
258 .Xr fclose 3 ,
259 .Xr fileno 3 ,
260 .Xr fseek 3 ,
261 .Xr funopen 3
262 .Sh STANDARDS
263 The
264 .Fn fopen
265 and
266 .Fn freopen
267 functions conform to
268 .St -ansiC .
269 All three functions are specified in
270 .St -p1003.1-2008 .
271 .Sh CAVEATS
272 Proper code using
273 .Fn fdopen
274 with error checking should
275 .Xr close 2
276 .Fa fildes
277 in case of failure, and
278 .Xr fclose 3
279 the resulting FILE * in case of success.
280 .Bd -literal
281 FILE *file;
282 int fd;
284 if ((file = fdopen(fd, "r")) != NULL) {
285 /* perform operations on the FILE * */
286 fclose(file);
287 } else {
288 /* failure, report the error */
289 close(fd);
290 }
291 .Ed