Debian Codegraph @

upstream/debian-unstable/man3/fopen.3

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