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