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