]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) 1990, 1991 The Regents of the University of California. |
2 | .\" 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 | .\" | |
a9cd9cb7 | 8 | .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) |
fea681da MK |
9 | .\" Redistribution and use in source and binary forms, with or without |
10 | .\" modification, are permitted provided that the following conditions | |
11 | .\" are met: | |
12 | .\" 1. Redistributions of source code must retain the above copyright | |
13 | .\" notice, this list of conditions and the following disclaimer. | |
14 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
15 | .\" notice, this list of conditions and the following disclaimer in the | |
16 | .\" documentation and/or other materials provided with the distribution. | |
17 | .\" 3. All advertising materials mentioning features or use of this software | |
18 | .\" must display the following acknowledgement: | |
19 | .\" This product includes software developed by the University of | |
20 | .\" California, Berkeley and its contributors. | |
21 | .\" 4. Neither the name of the University nor the names of its contributors | |
22 | .\" may be used to endorse or promote products derived from this software | |
23 | .\" without specific prior written permission. | |
24 | .\" | |
25 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
26 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
27 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
28 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
29 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
30 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
31 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
32 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
33 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
34 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
35 | .\" SUCH DAMAGE. | |
8c9302dc | 36 | .\" %%%LICENSE_END |
fea681da MK |
37 | .\" |
38 | .\" @(#)fopen.3 6.8 (Berkeley) 6/29/91 | |
39 | .\" | |
40 | .\" Converted for Linux, Mon Nov 29 15:22:01 1993, faith@cs.unc.edu | |
41 | .\" Modified, aeb, 960421, 970806 | |
42 | .\" Modified, joey, aeb, 2002-01-03 | |
43 | .\" | |
4b8c67d9 | 44 | .TH FOPEN 3 2017-09-15 "GNU" "Linux Programmer's Manual" |
fea681da MK |
45 | .SH NAME |
46 | fopen, fdopen, freopen \- stream open functions | |
47 | .SH SYNOPSIS | |
5895e7eb | 48 | .nf |
fea681da | 49 | .B #include <stdio.h> |
68e4db0a | 50 | .PP |
af500011 | 51 | .BI "FILE *fopen(const char *" pathname ", const char *" mode ); |
dbfe9c70 | 52 | .PP |
47752f33 | 53 | .BI "FILE *fdopen(int " fd ", const char *" mode ); |
dbfe9c70 | 54 | .PP |
af500011 | 55 | .BI "FILE *freopen(const char *" pathname ", const char *" mode ", FILE *" stream ); |
5895e7eb | 56 | .fi |
68e4db0a | 57 | .PP |
cc4615cc MK |
58 | .in -4n |
59 | Feature Test Macro Requirements for glibc (see | |
60 | .BR feature_test_macros (7)): | |
61 | .in | |
68e4db0a | 62 | .PP |
cc4615cc | 63 | .BR fdopen (): |
cff459de | 64 | _POSIX_C_SOURCE |
fea681da MK |
65 | .SH DESCRIPTION |
66 | The | |
e511ffb6 | 67 | .BR fopen () |
fea681da | 68 | function opens the file whose name is the string pointed to by |
af500011 | 69 | .I pathname |
fea681da MK |
70 | and associates a stream with it. |
71 | .PP | |
72 | The argument | |
73 | .I mode | |
74 | points to a string beginning with one of the following sequences | |
20e41f3f | 75 | (possibly followed by additional characters, as described below): |
fea681da MK |
76 | .TP |
77 | .B r | |
c13182ef MK |
78 | Open text file for reading. |
79 | The stream is positioned at the beginning of the file. | |
fea681da MK |
80 | .TP |
81 | .B r+ | |
c13182ef MK |
82 | Open for reading and writing. |
83 | The stream is positioned at the beginning of the file. | |
fea681da MK |
84 | .TP |
85 | .B w | |
c13182ef MK |
86 | Truncate file to zero length or create text file for writing. |
87 | The stream is positioned at the beginning of the file. | |
fea681da MK |
88 | .TP |
89 | .B w+ | |
c13182ef MK |
90 | Open for reading and writing. |
91 | The file is created if it does not exist, otherwise it is truncated. | |
92 | The stream is positioned at the beginning of | |
fea681da MK |
93 | the file. |
94 | .TP | |
95 | .B a | |
c13182ef MK |
96 | Open for appending (writing at end of file). |
97 | The file is created if it does not exist. | |
98 | The stream is positioned at the end of the file. | |
fea681da MK |
99 | .TP |
100 | .B a+ | |
c13182ef MK |
101 | Open for reading and appending (writing at end of file). |
102 | The file is created if it does not exist. | |
d66e1f2b | 103 | Output is always appended to the end of the file. |
492a6a0d | 104 | POSIX is silent on what the initial read position is when using this mode. |
d66e1f2b | 105 | For glibc, the initial file position for reading is at |
106 | the beginning of the file, but for Android/BSD/MacOS, the | |
492a6a0d | 107 | initial file position for reading is at the end of the file. |
fea681da MK |
108 | .PP |
109 | The | |
110 | .I mode | |
f81fb444 | 111 | string can also include the letter \(aqb\(aq either as a last character or as |
fea681da | 112 | a character between the characters in any of the two-character strings |
c13182ef MK |
113 | described above. |
114 | This is strictly for compatibility with C89 | |
f81fb444 | 115 | and has no effect; the \(aqb\(aq is ignored on all POSIX |
fea681da MK |
116 | conforming systems, including Linux. |
117 | (Other systems may treat text files and binary files differently, | |
f81fb444 | 118 | and adding the \(aqb\(aq may be a good idea if you do I/O to a binary |
008f1ecc | 119 | file and expect that your program may be ported to non-UNIX |
fea681da MK |
120 | environments.) |
121 | .PP | |
97004b99 MK |
122 | See NOTES below for details of glibc extensions for |
123 | .IR mode . | |
124 | .PP | |
c67f4a0a | 125 | Any created file will have the mode |
cab87712 | 126 | .BR S_IRUSR " | " S_IWUSR " | " S_IRGRP " | " S_IWGRP " | " S_IROTH " | " S_IWOTH |
fc7ba057 | 127 | (0666), as modified by the process's umask value (see |
fea681da MK |
128 | .BR umask (2)). |
129 | .PP | |
130 | Reads and writes may be intermixed on read/write streams in any order. | |
131 | Note that ANSI C requires that a file positioning function intervene | |
132 | between output and input, unless an input operation encounters end-of-file. | |
133 | (If this condition is not met, then a read is allowed to return the | |
134 | result of writes other than the most recent.) | |
135 | Therefore it is good practice (and indeed sometimes necessary | |
136 | under Linux) to put an | |
fb186734 | 137 | .BR fseek (3) |
fea681da | 138 | or |
fb186734 | 139 | .BR fgetpos (3) |
c13182ef | 140 | operation between write and read operations on such a stream. |
2f0af33b | 141 | This operation may be an apparent no-op |
a8d55537 | 142 | (as in \fIfseek(..., 0L, SEEK_CUR)\fP |
c4920f2b | 143 | called for its synchronizing side effect). |
fea681da | 144 | .PP |
a8d55537 | 145 | Opening a file in append mode (\fBa\fP as the first character of |
fea681da MK |
146 | .IR mode ) |
147 | causes all subsequent write operations to this stream to occur | |
96285a93 | 148 | at end-of-file, as if preceded the call: |
207050fa MK |
149 | .PP |
150 | .in +4n | |
151 | .EX | |
152 | fseek(stream, 0, SEEK_END); | |
153 | .EE | |
154 | .in | |
a8250b91 MK |
155 | .PP |
156 | The file descriptor associated with the stream is opened as if by a call to | |
157 | .BR open (2) | |
158 | with the following flags: | |
159 | .RS | |
160 | .TS | |
161 | allbox; | |
162 | lb lb | |
163 | c l. | |
164 | fopen() mode open() flags | |
165 | \fIr\fP O_RDONLY | |
166 | \fIw\fP O_WRONLY | O_CREAT | O_TRUNC | |
167 | \fIa\fP O_WRONLY | O_CREAT | O_APPEND | |
168 | \fIr+\fP O_RDWR | |
169 | \fIw+\fP O_RDWR | O_CREAT | O_TRUNC | |
170 | \fIa+\fP O_RDWR | O_CREAT | O_APPEND | |
171 | .TE | |
172 | .RE | |
f6386ed6 MK |
173 | .\" |
174 | .SS fdopen() | |
fea681da | 175 | The |
e511ffb6 | 176 | .BR fdopen () |
fea681da | 177 | function associates a stream with the existing file descriptor, |
47752f33 | 178 | .IR fd . |
fea681da MK |
179 | The |
180 | .I mode | |
181 | of the stream (one of the values "r", "r+", "w", "w+", "a", "a+") | |
182 | must be compatible with the mode of the file descriptor. | |
183 | The file position indicator of the new stream is set to that | |
184 | belonging to | |
47752f33 | 185 | .IR fd , |
fea681da MK |
186 | and the error and end-of-file indicators are cleared. |
187 | Modes "w" or "w+" do not cause truncation of the file. | |
188 | The file descriptor is not dup'ed, and will be closed when | |
189 | the stream created by | |
e511ffb6 | 190 | .BR fdopen () |
fea681da MK |
191 | is closed. |
192 | The result of applying | |
e511ffb6 | 193 | .BR fdopen () |
fea681da | 194 | to a shared memory object is undefined. |
f6386ed6 MK |
195 | .\" |
196 | .SS freopen() | |
fea681da | 197 | The |
e511ffb6 | 198 | .BR freopen () |
fea681da | 199 | function opens the file whose name is the string pointed to by |
af500011 | 200 | .I pathname |
fea681da MK |
201 | and associates the stream pointed to by |
202 | .I stream | |
c13182ef MK |
203 | with it. |
204 | The original stream (if it exists) is closed. | |
205 | The | |
fea681da MK |
206 | .I mode |
207 | argument is used just as in the | |
e511ffb6 | 208 | .BR fopen () |
c13182ef | 209 | function. |
847e0d88 | 210 | .PP |
7eed8a8f | 211 | If the |
af500011 | 212 | .I pathname |
7eed8a8f MK |
213 | argument is a null pointer, |
214 | .BR freopen () | |
215 | changes the mode of the stream to that specified in | |
216 | .IR mode ; | |
217 | that is, | |
218 | .BR freopen () | |
219 | reopens the pathname that is associated with the stream. | |
220 | The specification for this behavior was added in the C99 standard, which says: | |
847e0d88 | 221 | .PP |
7eed8a8f MK |
222 | .RS |
223 | In this case, | |
224 | the file descriptor associated with the stream need not be closed | |
225 | if the call to | |
226 | .BR freopen () | |
227 | succeeds. | |
228 | It is implementation-defined which changes of mode are permitted (if any), | |
229 | and under what circumstances. | |
230 | .RE | |
231 | .PP | |
c13182ef | 232 | The primary use of the |
e511ffb6 | 233 | .BR freopen () |
fea681da | 234 | function is to change the file associated with a standard text stream |
b9d200ce | 235 | .RI ( stderr ", " stdin ", or " stdout ). |
47297adb | 236 | .SH RETURN VALUE |
fea681da | 237 | Upon successful completion |
e511ffb6 MK |
238 | .BR fopen (), |
239 | .BR fdopen () | |
fea681da | 240 | and |
e511ffb6 | 241 | .BR freopen () |
fea681da | 242 | return a |
836f07c1 | 243 | .I FILE |
c13182ef | 244 | pointer. |
28d03ce9 | 245 | Otherwise, NULL is returned and |
fea681da MK |
246 | .I errno |
247 | is set to indicate the error. | |
248 | .SH ERRORS | |
249 | .TP | |
250 | .B EINVAL | |
251 | The | |
252 | .I mode | |
253 | provided to | |
e511ffb6 MK |
254 | .BR fopen (), |
255 | .BR fdopen (), | |
fea681da | 256 | or |
e511ffb6 | 257 | .BR freopen () |
fea681da MK |
258 | was invalid. |
259 | .PP | |
260 | The | |
e511ffb6 MK |
261 | .BR fopen (), |
262 | .BR fdopen () | |
fea681da | 263 | and |
e511ffb6 | 264 | .BR freopen () |
fea681da MK |
265 | functions may also fail and set |
266 | .I errno | |
267 | for any of the errors specified for the routine | |
268 | .BR malloc (3). | |
269 | .PP | |
270 | The | |
e511ffb6 | 271 | .BR fopen () |
fea681da MK |
272 | function may also fail and set |
273 | .I errno | |
274 | for any of the errors specified for the routine | |
275 | .BR open (2). | |
276 | .PP | |
277 | The | |
e511ffb6 | 278 | .BR fdopen () |
fea681da MK |
279 | function may also fail and set |
280 | .I errno | |
281 | for any of the errors specified for the routine | |
282 | .BR fcntl (2). | |
283 | .PP | |
284 | The | |
e511ffb6 | 285 | .BR freopen () |
fea681da MK |
286 | function may also fail and set |
287 | .I errno | |
288 | for any of the errors specified for the routines | |
289 | .BR open (2), | |
9af134cd | 290 | .BR fclose (3), |
fea681da MK |
291 | and |
292 | .BR fflush (3). | |
418ee2e8 MS |
293 | .SH ATTRIBUTES |
294 | For an explanation of the terms used in this section, see | |
295 | .BR attributes (7). | |
296 | .TS | |
297 | allbox; | |
298 | lbw28 lb lb | |
299 | l l l. | |
300 | Interface Attribute Value | |
301 | T{ | |
302 | .BR fopen (), | |
303 | .BR fdopen (), | |
304 | .BR freopen () | |
305 | T} Thread safety MT-Safe | |
306 | .TE | |
47297adb | 307 | .SH CONFORMING TO |
bb7091c0 MK |
308 | .BR fopen (), |
309 | .BR freopen (): | |
310 | POSIX.1-2001, POSIX.1-2008, C89, C99. | |
847e0d88 | 311 | .PP |
bb7091c0 MK |
312 | .BR fdopen (): |
313 | POSIX.1-2001, POSIX.1-2008. | |
d597239c | 314 | .SH NOTES |
c634028a | 315 | .SS Glibc notes |
3ed4fcbd | 316 | The GNU C library allows the following extensions for the string specified in |
a30e090e MK |
317 | .IR mode : |
318 | .TP | |
bcd70adc | 319 | .BR c " (since glibc 2.3.3)" |
c13182ef | 320 | Do not make the open operation, |
bcd70adc MK |
321 | or subsequent read and write operations, |
322 | thread cancellation points. | |
78a9ad25 MK |
323 | This flag is ignored for |
324 | .BR fdopen (). | |
bcd70adc | 325 | .TP |
d8d79fa2 MK |
326 | .BR e " (since glibc 2.7)" |
327 | Open the file with the | |
328 | .B O_CLOEXEC | |
329 | flag. | |
330 | See | |
331 | .BR open (2) | |
332 | for more information. | |
78a9ad25 MK |
333 | This flag is ignored for |
334 | .BR fdopen (). | |
d8d79fa2 | 335 | .TP |
bcd70adc | 336 | .BR m " (since glibc 2.3)" |
c13182ef | 337 | Attempt to access the file using |
bcd70adc | 338 | .BR mmap (2), |
c13182ef | 339 | rather than I/O system calls |
bcd70adc MK |
340 | .RB ( read (2), |
341 | .BR write (2)). | |
c13182ef | 342 | Currently, |
bcd70adc | 343 | .\" As at glibc 2.4: |
2d2c82e1 | 344 | use of |
bcd70adc | 345 | .BR mmap (2) |
33a0ccb2 | 346 | is attempted only for a file opened for reading. |
bcd70adc | 347 | .TP |
a30e090e | 348 | .B x |
accdf645 | 349 | .\" Since glibc 2.0? |
bea08fec | 350 | .\" FIXME . C11 specifies this flag |
a30e090e | 351 | Open the file exclusively |
c13182ef | 352 | (like the |
a30e090e MK |
353 | .B O_EXCL |
354 | flag of | |
355 | .BR open (2)). | |
356 | If the file already exists, | |
357 | .BR fopen () | |
358 | fails, and sets | |
359 | .I errno | |
360 | to | |
361 | .BR EEXIST . | |
bcd70adc MK |
362 | This flag is ignored for |
363 | .BR fdopen (). | |
d33e8466 MK |
364 | .PP |
365 | In addition to the above characters, | |
366 | .BR fopen () | |
367 | and | |
368 | .BR freopen () | |
afd6f6c5 | 369 | support the following syntax |
d33e8466 MK |
370 | in |
371 | .IR mode : | |
847e0d88 | 372 | .PP |
d33e8466 | 373 | .BI " ,ccs=" string |
847e0d88 | 374 | .PP |
d33e8466 MK |
375 | The given |
376 | .I string | |
377 | is taken as the name of a coded character set and | |
378 | the stream is marked as wide-oriented. | |
379 | Thereafter, internal conversion functions convert I/O | |
380 | to and from the character set | |
381 | .IR string . | |
382 | If the | |
383 | .BI ,ccs= string | |
384 | syntax is not specified, | |
385 | then the wide-orientation of the stream is | |
386 | determined by the first file operation. | |
afd6f6c5 | 387 | If that operation is a wide-character operation, |
d33e8466 MK |
388 | the stream is marked wide-oriented, |
389 | and functions to convert to the coded character set are loaded. | |
4d9edb6e | 390 | .SH BUGS |
afd6f6c5 MK |
391 | When parsing for individual flag characters in |
392 | .IR mode | |
6f0f6cf6 | 393 | (i.e., the characters preceding the "ccs" specification), |
afd6f6c5 | 394 | the glibc implementation of |
bea08fec | 395 | .\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=12685 |
4d9edb6e MK |
396 | .BR fopen () |
397 | and | |
398 | .BR freopen () | |
399 | limits the number of characters examined in | |
400 | .I mode | |
401 | to 7 (or, in glibc versions before 2.14, to 6, | |
402 | which was not enough to include possible specifications such as "rb+cmxe"). | |
403 | The current implementation of | |
404 | .BR fdopen () | |
6f0f6cf6 | 405 | parses at most 5 characters in |
4d9edb6e | 406 | .IR mode . |
47297adb | 407 | .SH SEE ALSO |
fea681da MK |
408 | .BR open (2), |
409 | .BR fclose (3), | |
5f0aa64a PB |
410 | .BR fileno (3), |
411 | .BR fmemopen (3), | |
a6bd38c6 MK |
412 | .BR fopencookie (3), |
413 | .BR open_memstream (3) |