1fopen(3) Library Functions Manual fopen(3)
2
6 fopen, fdopen, freopen - stream open functions
7
9 Standard C library (libc, -lc)
10
12 #include <stdio.h>
13 FILE *fopen(const char *restrict pathname, const char *restrict mode);
15 FILE *fdopen(int fd, const char *mode);
16 FILE *freopen(const char *restrict pathname, const char *restrict mode,
17 FILE *restrict stream);
18 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
20 fdopen():
22 _POSIX_C_SOURCE
23
25 The fopen() function opens the file whose name is the string pointed to
26 by pathname and associates a stream with it.
27 The argument mode points to a string beginning with one of the follow‐
29 ing sequences (possibly followed by additional characters, as described
30 below):
31 r Open text file for reading. The stream is positioned at the be‐
33 ginning of the file.
34 r+ Open for reading and writing. The stream is positioned at the
36 beginning of the file.
37 w Truncate file to zero length or create text file for writing.
39 The stream is positioned at the beginning of the file.
40 w+ Open for reading and writing. The file is created if it does
42 not exist, otherwise it is truncated. The stream is positioned
43 at the beginning of the file.
44 a Open for appending (writing at end of file). The file is cre‐
46 ated if it does not exist. The stream is positioned at the end
47 of the file.
48 a+ Open for reading and appending (writing at end of file). The
50 file is created if it does not exist. Output is always appended
51 to the end of the file. POSIX is silent on what the initial
52 read position is when using this mode. For glibc, the initial
53 file position for reading is at the beginning of the file, but
54 for Android/BSD/MacOS, the initial file position for reading is
55 at the end of the file.
56 The mode string can also include the letter 'b' either as a last char‐
58 acter or as a character between the characters in any of the two-char‐
59 acter strings described above. This is strictly for compatibility with
60 ISO C and has no effect; the 'b' is ignored on all POSIX conforming
61 systems, including Linux. (Other systems may treat text files and bi‐
62 nary files differently, and adding the 'b' may be a good idea if you do
63 I/O to a binary file and expect that your program may be ported to non-
64 UNIX environments.)
65 See NOTES below for details of glibc extensions for mode.
67 Any created file will have the mode S_IRUSR | S_IWUSR | S_IRGRP | S_IW‐
69 GRP | S_IROTH | S_IWOTH [22m(0666), as modified by the process's umask
70 value (see umask(2)).
71 Reads and writes may be intermixed on read/write streams in any order.
73 Note that ANSI C requires that a file positioning function intervene
74 between output and input, unless an input operation encounters end-of-
75 file. (If this condition is not met, then a read is allowed to return
76 the result of writes other than the most recent.) Therefore it is good
77 practice (and indeed sometimes necessary under Linux) to put an
78 fseek(3) or fsetpos(3) operation between write and read operations on
79 such a stream. This operation may be an apparent no-op (as in
80 fseek(..., 0L, SEEK_CUR) called for its synchronizing side effect).
81 Opening a file in append mode (a as the first character of mode) causes
83 all subsequent write operations to this stream to occur at end-of-file,
84 as if preceded by the call:
85 fseek(stream, 0, SEEK_END);
87 The file descriptor associated with the stream is opened as if by a
89 call to open(2) with the following flags:
90 ┌─────────────┬───────────────────────────────┐
92 │fopen() mode │ open() flags │
93 ├─────────────┼───────────────────────────────┤
94 │ r │ O_RDONLY │
95 ├─────────────┼───────────────────────────────┤
96 │ w │ O_WRONLY | O_CREAT | O_TRUNC │
97 ├─────────────┼───────────────────────────────┤
98 │ a │ O_WRONLY | O_CREAT | O_APPEND │
99 ├─────────────┼───────────────────────────────┤
100 │ r+ │ O_RDWR │
101 ├─────────────┼───────────────────────────────┤
102 │ w+ │ O_RDWR | O_CREAT | O_TRUNC │
103 ├─────────────┼───────────────────────────────┤
104 │ a+ │ O_RDWR | O_CREAT | O_APPEND │
105 └─────────────┴───────────────────────────────┘
106 fdopen()
107 The fdopen() function associates a stream with the existing file de‐
108 scriptor, fd. The mode of the stream (one of the values "r", "r+",
109 "w", "w+", "a", "a+") must be compatible with the mode of the file de‐
110 scriptor. The file position indicator of the new stream is set to that
111 belonging to fd, and the error and end-of-file indicators are cleared.
112 Modes "w" or "w+" do not cause truncation of the file. The file de‐
113 scriptor is not dup'ed, and will be closed when the stream created by
114 fdopen() is closed. The result of applying fdopen() to a shared memory
115 object is undefined.
116 freopen()
118 The freopen() function opens the file whose name is the string pointed
119 to by pathname and associates the stream pointed to by stream with it.
120 The original stream (if it exists) is closed. The mode argument is
121 used just as in the fopen() function.
122 If the pathname argument is a null pointer, freopen() changes the mode
124 of the stream to that specified in mode; that is, freopen() reopens the
125 pathname that is associated with the stream. The specification for
126 this behavior was added in the C99 standard, which says:
127 In this case, the file descriptor associated with the stream
129 need not be closed if the call to freopen() succeeds. It is im‐
130 plementation-defined which changes of mode are permitted (if
131 any), and under what circumstances.
132 The primary use of the freopen() function is to change the file associ‐
134 ated with a standard text stream (stderr, stdin, or stdout).
135
137 Upon successful completion fopen(), fdopen(), and freopen() return a
138 FILE pointer. Otherwise, NULL is returned and errno is set to indicate
139 the error.
140
142 EINVAL The mode provided to fopen(), fdopen(), or freopen() was in‐
143 valid.
144 The fopen(), fdopen(), and freopen() functions may also fail and set
146 errno for any of the errors specified for the routine malloc(3).
147 The fopen() function may also fail and set errno for any of the errors
149 specified for the routine open(2).
150 The fdopen() function may also fail and set errno for any of the errors
152 specified for the routine fcntl(2).
153 The freopen() function may also fail and set errno for any of the er‐
155 rors specified for the routines open(2), fclose(3), and fflush(3).
156
158 For an explanation of the terms used in this section, see at‐
159 tributes(7).
160 ┌────────────────────────────────────────────┬───────────────┬─────────┐
162 │Interface │ Attribute │ Value │
163 ├────────────────────────────────────────────┼───────────────┼─────────┤
164 │fopen(), fdopen(), freopen() │ Thread safety │ MT-Safe │
165 └────────────────────────────────────────────┴───────────────┴─────────┘
166
168 fopen()
169 freopen()
170 C11, POSIX.1-2008.
171 fdopen()
173 POSIX.1-2008.
174
176 fopen()
177 freopen()
178 POSIX.1-2001, C89.
179 fdopen()
181 POSIX.1-2001.
182
184 glibc notes
185 The GNU C library allows the following extensions for the string
186 specified in mode:
187 c (since glibc 2.3.3)
189 Do not make the open operation, or subsequent read and write
190 operations, thread cancelation points. This flag is ignored for
191 fdopen().
192 e (since glibc 2.7)
194 Open the file with the O_CLOEXEC flag. See open(2) for more
195 information. This flag is ignored for fdopen().
196 m (since glibc 2.3)
198 Attempt to access the file using mmap(2), rather than I/O system
199 calls (read(2), write(2)). Currently, use of mmap(2) is
200 attempted only for a file opened for reading.
201 x Open the file exclusively (like the O_EXCL flag of open(2)). If
203 the file already exists, fopen() fails, and sets errno to
204 EEXIST. This flag is ignored for fdopen().
205 In addition to the above characters, fopen() and freopen() support the
207 following syntax in mode:
208 ,ccs=string
210 The given string is taken as the name of a coded character set and the
212 stream is marked as wide-oriented. Thereafter, internal conversion
213 functions convert I/O to and from the character set string. If the
214 ,ccs=string syntax is not specified, then the wide-orientation of the
215 stream is determined by the first file operation. If that operation is
216 a wide-character operation, the stream is marked wide-oriented, and
217 functions to convert to the coded character set are loaded.
218
220 When parsing for individual flag characters in mode (i.e., the
221 characters preceding the "ccs" specification), the glibc implementation
222 of fopen() and freopen() limits the number of characters examined in
223 mode to 7 (or, before glibc 2.14, to 6, which was not enough to include
224 possible specifications such as "rb+cmxe"). The current implementation
225 of fdopen() parses at most 5 characters in mode.
226
228 open(2), fclose(3), fileno(3), fmemopen(3), fopencookie(3),
229 open_memstream(3)
230Linux man-pages 6.05 2023-07-20 fopen(3)