]>
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. | |
be9dccdf MK |
103 | The initial file position for reading is at the beginning of the file, |
104 | but output is always appended to the end of the file. | |
fea681da MK |
105 | .PP |
106 | The | |
107 | .I mode | |
f81fb444 | 108 | string can also include the letter \(aqb\(aq either as a last character or as |
fea681da | 109 | a character between the characters in any of the two-character strings |
c13182ef MK |
110 | described above. |
111 | This is strictly for compatibility with C89 | |
f81fb444 | 112 | and has no effect; the \(aqb\(aq is ignored on all POSIX |
fea681da MK |
113 | conforming systems, including Linux. |
114 | (Other systems may treat text files and binary files differently, | |
f81fb444 | 115 | and adding the \(aqb\(aq may be a good idea if you do I/O to a binary |
008f1ecc | 116 | file and expect that your program may be ported to non-UNIX |
fea681da MK |
117 | environments.) |
118 | .PP | |
97004b99 MK |
119 | See NOTES below for details of glibc extensions for |
120 | .IR mode . | |
121 | .PP | |
c67f4a0a | 122 | Any created file will have the mode |
cab87712 | 123 | .BR S_IRUSR " | " S_IWUSR " | " S_IRGRP " | " S_IWGRP " | " S_IROTH " | " S_IWOTH |
fc7ba057 | 124 | (0666), as modified by the process's umask value (see |
fea681da MK |
125 | .BR umask (2)). |
126 | .PP | |
127 | Reads and writes may be intermixed on read/write streams in any order. | |
128 | Note that ANSI C requires that a file positioning function intervene | |
129 | between output and input, unless an input operation encounters end-of-file. | |
130 | (If this condition is not met, then a read is allowed to return the | |
131 | result of writes other than the most recent.) | |
132 | Therefore it is good practice (and indeed sometimes necessary | |
133 | under Linux) to put an | |
fb186734 | 134 | .BR fseek (3) |
fea681da | 135 | or |
fb186734 | 136 | .BR fgetpos (3) |
c13182ef | 137 | operation between write and read operations on such a stream. |
2f0af33b | 138 | This operation may be an apparent no-op |
a8d55537 | 139 | (as in \fIfseek(..., 0L, SEEK_CUR)\fP |
c4920f2b | 140 | called for its synchronizing side effect). |
fea681da | 141 | .PP |
a8d55537 | 142 | Opening a file in append mode (\fBa\fP as the first character of |
fea681da MK |
143 | .IR mode ) |
144 | causes all subsequent write operations to this stream to occur | |
96285a93 | 145 | at end-of-file, as if preceded the call: |
207050fa MK |
146 | .PP |
147 | .in +4n | |
148 | .EX | |
149 | fseek(stream, 0, SEEK_END); | |
150 | .EE | |
151 | .in | |
a8250b91 MK |
152 | .PP |
153 | The file descriptor associated with the stream is opened as if by a call to | |
154 | .BR open (2) | |
155 | with the following flags: | |
156 | .RS | |
157 | .TS | |
158 | allbox; | |
159 | lb lb | |
160 | c l. | |
161 | fopen() mode open() flags | |
162 | \fIr\fP O_RDONLY | |
163 | \fIw\fP O_WRONLY | O_CREAT | O_TRUNC | |
164 | \fIa\fP O_WRONLY | O_CREAT | O_APPEND | |
165 | \fIr+\fP O_RDWR | |
166 | \fIw+\fP O_RDWR | O_CREAT | O_TRUNC | |
167 | \fIa+\fP O_RDWR | O_CREAT | O_APPEND | |
168 | .TE | |
169 | .RE | |
f6386ed6 MK |
170 | .\" |
171 | .SS fdopen() | |
fea681da | 172 | The |
e511ffb6 | 173 | .BR fdopen () |
fea681da | 174 | function associates a stream with the existing file descriptor, |
47752f33 | 175 | .IR fd . |
fea681da MK |
176 | The |
177 | .I mode | |
178 | of the stream (one of the values "r", "r+", "w", "w+", "a", "a+") | |
179 | must be compatible with the mode of the file descriptor. | |
180 | The file position indicator of the new stream is set to that | |
181 | belonging to | |
47752f33 | 182 | .IR fd , |
fea681da MK |
183 | and the error and end-of-file indicators are cleared. |
184 | Modes "w" or "w+" do not cause truncation of the file. | |
185 | The file descriptor is not dup'ed, and will be closed when | |
186 | the stream created by | |
e511ffb6 | 187 | .BR fdopen () |
fea681da MK |
188 | is closed. |
189 | The result of applying | |
e511ffb6 | 190 | .BR fdopen () |
fea681da | 191 | to a shared memory object is undefined. |
f6386ed6 MK |
192 | .\" |
193 | .SS freopen() | |
fea681da | 194 | The |
e511ffb6 | 195 | .BR freopen () |
fea681da | 196 | function opens the file whose name is the string pointed to by |
af500011 | 197 | .I pathname |
fea681da MK |
198 | and associates the stream pointed to by |
199 | .I stream | |
c13182ef MK |
200 | with it. |
201 | The original stream (if it exists) is closed. | |
202 | The | |
fea681da MK |
203 | .I mode |
204 | argument is used just as in the | |
e511ffb6 | 205 | .BR fopen () |
c13182ef | 206 | function. |
847e0d88 | 207 | .PP |
7eed8a8f | 208 | If the |
af500011 | 209 | .I pathname |
7eed8a8f MK |
210 | argument is a null pointer, |
211 | .BR freopen () | |
212 | changes the mode of the stream to that specified in | |
213 | .IR mode ; | |
214 | that is, | |
215 | .BR freopen () | |
216 | reopens the pathname that is associated with the stream. | |
217 | The specification for this behavior was added in the C99 standard, which says: | |
847e0d88 | 218 | .PP |
7eed8a8f MK |
219 | .RS |
220 | In this case, | |
221 | the file descriptor associated with the stream need not be closed | |
222 | if the call to | |
223 | .BR freopen () | |
224 | succeeds. | |
225 | It is implementation-defined which changes of mode are permitted (if any), | |
226 | and under what circumstances. | |
227 | .RE | |
228 | .PP | |
c13182ef | 229 | The primary use of the |
e511ffb6 | 230 | .BR freopen () |
fea681da | 231 | function is to change the file associated with a standard text stream |
b9d200ce | 232 | .RI ( stderr ", " stdin ", or " stdout ). |
47297adb | 233 | .SH RETURN VALUE |
fea681da | 234 | Upon successful completion |
e511ffb6 MK |
235 | .BR fopen (), |
236 | .BR fdopen () | |
fea681da | 237 | and |
e511ffb6 | 238 | .BR freopen () |
fea681da | 239 | return a |
836f07c1 | 240 | .I FILE |
c13182ef | 241 | pointer. |
28d03ce9 | 242 | Otherwise, NULL is returned and |
fea681da MK |
243 | .I errno |
244 | is set to indicate the error. | |
245 | .SH ERRORS | |
246 | .TP | |
247 | .B EINVAL | |
248 | The | |
249 | .I mode | |
250 | provided to | |
e511ffb6 MK |
251 | .BR fopen (), |
252 | .BR fdopen (), | |
fea681da | 253 | or |
e511ffb6 | 254 | .BR freopen () |
fea681da MK |
255 | was invalid. |
256 | .PP | |
257 | The | |
e511ffb6 MK |
258 | .BR fopen (), |
259 | .BR fdopen () | |
fea681da | 260 | and |
e511ffb6 | 261 | .BR freopen () |
fea681da MK |
262 | functions may also fail and set |
263 | .I errno | |
264 | for any of the errors specified for the routine | |
265 | .BR malloc (3). | |
266 | .PP | |
267 | The | |
e511ffb6 | 268 | .BR fopen () |
fea681da MK |
269 | function may also fail and set |
270 | .I errno | |
271 | for any of the errors specified for the routine | |
272 | .BR open (2). | |
273 | .PP | |
274 | The | |
e511ffb6 | 275 | .BR fdopen () |
fea681da MK |
276 | function may also fail and set |
277 | .I errno | |
278 | for any of the errors specified for the routine | |
279 | .BR fcntl (2). | |
280 | .PP | |
281 | The | |
e511ffb6 | 282 | .BR freopen () |
fea681da MK |
283 | function may also fail and set |
284 | .I errno | |
285 | for any of the errors specified for the routines | |
286 | .BR open (2), | |
9af134cd | 287 | .BR fclose (3), |
fea681da MK |
288 | and |
289 | .BR fflush (3). | |
418ee2e8 MS |
290 | .SH ATTRIBUTES |
291 | For an explanation of the terms used in this section, see | |
292 | .BR attributes (7). | |
293 | .TS | |
294 | allbox; | |
295 | lbw28 lb lb | |
296 | l l l. | |
297 | Interface Attribute Value | |
298 | T{ | |
299 | .BR fopen (), | |
300 | .BR fdopen (), | |
301 | .BR freopen () | |
302 | T} Thread safety MT-Safe | |
303 | .TE | |
47297adb | 304 | .SH CONFORMING TO |
bb7091c0 MK |
305 | .BR fopen (), |
306 | .BR freopen (): | |
307 | POSIX.1-2001, POSIX.1-2008, C89, C99. | |
847e0d88 | 308 | .PP |
bb7091c0 MK |
309 | .BR fdopen (): |
310 | POSIX.1-2001, POSIX.1-2008. | |
d597239c | 311 | .SH NOTES |
c634028a | 312 | .SS Glibc notes |
3ed4fcbd | 313 | The GNU C library allows the following extensions for the string specified in |
a30e090e MK |
314 | .IR mode : |
315 | .TP | |
bcd70adc | 316 | .BR c " (since glibc 2.3.3)" |
c13182ef | 317 | Do not make the open operation, |
bcd70adc MK |
318 | or subsequent read and write operations, |
319 | thread cancellation points. | |
78a9ad25 MK |
320 | This flag is ignored for |
321 | .BR fdopen (). | |
bcd70adc | 322 | .TP |
d8d79fa2 MK |
323 | .BR e " (since glibc 2.7)" |
324 | Open the file with the | |
325 | .B O_CLOEXEC | |
326 | flag. | |
327 | See | |
328 | .BR open (2) | |
329 | for more information. | |
78a9ad25 MK |
330 | This flag is ignored for |
331 | .BR fdopen (). | |
d8d79fa2 | 332 | .TP |
bcd70adc | 333 | .BR m " (since glibc 2.3)" |
c13182ef | 334 | Attempt to access the file using |
bcd70adc | 335 | .BR mmap (2), |
c13182ef | 336 | rather than I/O system calls |
bcd70adc MK |
337 | .RB ( read (2), |
338 | .BR write (2)). | |
c13182ef | 339 | Currently, |
bcd70adc | 340 | .\" As at glibc 2.4: |
2d2c82e1 | 341 | use of |
bcd70adc | 342 | .BR mmap (2) |
33a0ccb2 | 343 | is attempted only for a file opened for reading. |
bcd70adc | 344 | .TP |
a30e090e | 345 | .B x |
accdf645 | 346 | .\" Since glibc 2.0? |
bea08fec | 347 | .\" FIXME . C11 specifies this flag |
a30e090e | 348 | Open the file exclusively |
c13182ef | 349 | (like the |
a30e090e MK |
350 | .B O_EXCL |
351 | flag of | |
352 | .BR open (2)). | |
353 | If the file already exists, | |
354 | .BR fopen () | |
355 | fails, and sets | |
356 | .I errno | |
357 | to | |
358 | .BR EEXIST . | |
bcd70adc MK |
359 | This flag is ignored for |
360 | .BR fdopen (). | |
d33e8466 MK |
361 | .PP |
362 | In addition to the above characters, | |
363 | .BR fopen () | |
364 | and | |
365 | .BR freopen () | |
afd6f6c5 | 366 | support the following syntax |
d33e8466 MK |
367 | in |
368 | .IR mode : | |
847e0d88 | 369 | .PP |
d33e8466 | 370 | .BI " ,ccs=" string |
847e0d88 | 371 | .PP |
d33e8466 MK |
372 | The given |
373 | .I string | |
374 | is taken as the name of a coded character set and | |
375 | the stream is marked as wide-oriented. | |
376 | Thereafter, internal conversion functions convert I/O | |
377 | to and from the character set | |
378 | .IR string . | |
379 | If the | |
380 | .BI ,ccs= string | |
381 | syntax is not specified, | |
382 | then the wide-orientation of the stream is | |
383 | determined by the first file operation. | |
afd6f6c5 | 384 | If that operation is a wide-character operation, |
d33e8466 MK |
385 | the stream is marked wide-oriented, |
386 | and functions to convert to the coded character set are loaded. | |
4d9edb6e | 387 | .SH BUGS |
afd6f6c5 MK |
388 | When parsing for individual flag characters in |
389 | .IR mode | |
6f0f6cf6 | 390 | (i.e., the characters preceding the "ccs" specification), |
afd6f6c5 | 391 | the glibc implementation of |
bea08fec | 392 | .\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=12685 |
4d9edb6e MK |
393 | .BR fopen () |
394 | and | |
395 | .BR freopen () | |
396 | limits the number of characters examined in | |
397 | .I mode | |
398 | to 7 (or, in glibc versions before 2.14, to 6, | |
399 | which was not enough to include possible specifications such as "rb+cmxe"). | |
400 | The current implementation of | |
401 | .BR fdopen () | |
6f0f6cf6 | 402 | parses at most 5 characters in |
4d9edb6e | 403 | .IR mode . |
47297adb | 404 | .SH SEE ALSO |
fea681da MK |
405 | .BR open (2), |
406 | .BR fclose (3), | |
5f0aa64a PB |
407 | .BR fileno (3), |
408 | .BR fmemopen (3), | |
a6bd38c6 MK |
409 | .BR fopencookie (3), |
410 | .BR open_memstream (3) |