| blob | c82140269451cf314fa69b6f2cc29c09f6a7a443 |
1 .\" Copyright (c) 1990, 1991, 1993
2 .\" The Regents of the University of California. 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 .\"
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
10 .\" are met:
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in the
15 .\" documentation and/or other materials provided with the distribution.
16 .\" 3. Neither the name of the University nor the names of its contributors
17 .\" may be used to endorse or promote products derived from this software
18 .\" without specific prior written permission.
19 .\"
20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30 .\" SUCH DAMAGE.
31 .\"
32 .\" @(#)fopen.3 8.1 (Berkeley) 6/4/93
33 .\" $FreeBSD: src/lib/libc/stdio/fopen.3,v 1.20 2007/01/09 00:28:06 imp Exp $
34 .\" $DragonFly: src/lib/libc/stdio/fopen.3,v 1.4 2007/04/04 18:36:55 swildner Exp $
35 .\"
36 .Dd June 8, 2004
37 .Dt FOPEN 3
38 .Os
39 .Sh NAME
40 .Nm fopen ,
41 .Nm fdopen ,
42 .Nm freopen
43 .Nd stream open functions
44 .Sh LIBRARY
45 .Lb libc
46 .Sh SYNOPSIS
47 .In stdio.h
48 .Ft FILE *
49 .Fn fopen "const char * restrict path" "const char * restrict mode"
50 .Ft FILE *
51 .Fn fdopen "int fildes" "const char *mode"
52 .Ft FILE *
53 .Fn freopen "const char *path" "const char *mode" "FILE *stream"
54 .Sh DESCRIPTION
55 The
56 .Fn fopen
57 function
58 opens the file whose name is the string pointed to by
59 .Fa path
60 and associates a stream with it.
61 .Pp
62 The argument
63 .Fa mode
64 points to a string beginning with one of the following
65 sequences (Additional characters may follow these sequences.):
66 .Bl -tag -width indent
67 .It Dq Li r
68 Open file for reading.
69 The stream is positioned at the beginning of the file.
70 .It Dq Li w
71 Open file for writing.
72 Creates the file if it does not already exist,
73 truncates the file if it does.
74 .It Dq Li a
75 Open file for append.
76 Creates the file if it does not already exist.
77 Seeks to end of the file.
78 Subsequent writes to the file will always end up at the then current
79 end of file, irrespective of any intervening
80 .Xr fseek 3
81 or similar operation.
82 .El
83 .Pp
84 Additional flags may modify the primary mode as follows:
85 .Bl -tag -width indent
86 .It Dq Li +
87 The file will be opened for both reading and writing.
88 For example 'r+' or 'w+'.
89 .It Dq Li x
90 The open will fail if the file already exists (C11).
91 For example 'wx'.
92 .It Dq Li e
93 Close-on-exec. The underlying descriptor will automatically be closed on
94 any exec() (glibc compatibility).
95 .It Dq Li b
96 Binary mode. On UNIX systems file reading and writing is always in binary
97 mode so this flag has no effect.
98 .El
99 .Pp
100 The
101 .Fa mode
102 string can also include the letter ``b'' either as a third character or
103 as a character between the characters in any of the two-character strings
104 described above.
105 This is strictly for compatibility with
106 .St -isoC-2011
107 and has no effect; the ``b'' is ignored.
108 .Pp
109 Any created files will have mode
110 .Pf \\*q Dv S_IRUSR
111 \&|
112 .Dv S_IWUSR
113 \&|
114 .Dv S_IRGRP
115 \&|
116 .Dv S_IWGRP
117 \&|
118 .Dv S_IROTH
119 \&|
120 .Dv S_IWOTH Ns \\*q
121 .Pq Li 0666 ,
122 as modified by the process'
123 umask value (see
124 .Xr umask 2 ) .
125 .Pp
126 Reads and writes may be intermixed on read/write streams in any order,
127 and do not require an intermediate seek as in previous versions of
128 .Em stdio .
129 This is not portable to other systems, however;
130 .Tn ANSI C
131 requires that
132 a file positioning function intervene between output and input, unless
133 an input operation encounters end-of-file.
134 .Pp
135 The
136 .Fn fdopen
137 function associates a stream with the existing file descriptor,
138 .Fa fildes .
139 The mode
140 of the stream must be compatible with the mode of the file descriptor.
141 When the stream is closed via
142 .Xr fclose 3 ,
143 .Fa fildes
144 is closed also.
145 .Pp
146 The
147 .Fn freopen
148 function
149 opens the file whose name is the string pointed to by
150 .Fa path
151 and associates the stream pointed to by
152 .Fa stream
153 with it.
154 The original stream (if it exists) is closed.
155 The
156 .Fa mode
157 argument is used just as in the
158 .Fn fopen
159 function.
160 .Pp
161 If the
162 .Fa path
163 argument is
164 .Dv NULL ,
165 .Fn freopen
166 attempts to re-open the file associated with
167 .Fa stream
168 with a new mode.
169 The new mode must be compatible with the mode that the stream was originally
170 opened with:
171 .Bl -bullet -offset indent
172 .It
173 Streams originally opened with mode
174 .Dq Li r
175 can only be reopened with that same mode.
176 .It
177 Streams originally opened with mode
178 .Dq Li a
179 can be reopened with the same mode, or mode
180 .Dq Li w .
181 .It
182 Streams originally opened with mode
183 .Dq Li w
184 can be reopened with the same mode, or mode
185 .Dq Li a .
186 .It
187 Streams originally opened with mode
188 .Dq Li r+ ,
189 .Dq Li w+ ,
190 or
191 .Dq Li a+
192 can be reopened with any mode.
193 .El
194 .Pp
195 The primary use of the
196 .Fn freopen
197 function
198 is to change the file associated with a
199 standard text stream
200 .Dv ( stderr , stdin ,
201 or
202 .Dv stdout ) .
203 .Sh RETURN VALUES
204 Upon successful completion
205 .Fn fopen ,
206 .Fn fdopen
207 and
208 .Fn freopen
209 return a
210 .Tn FILE
211 pointer.
212 Otherwise,
213 .Dv NULL
214 is returned and the global variable
215 .Va errno
216 is set to indicate the error.
217 .Sh ERRORS
218 .Bl -tag -width Er
219 .It Bq Er EINVAL
220 The
221 .Fa mode
222 argument
223 to
224 .Fn fopen ,
225 .Fn fdopen ,
226 or
227 .Fn freopen
228 was invalid.
229 .El
230 .Pp
231 The
232 .Fn fopen ,
233 .Fn fdopen
234 and
235 .Fn freopen
236 functions
237 may also fail and set
238 .Va errno
239 for any of the errors specified for the routine
240 .Xr malloc 3 .
241 .Pp
242 The
243 .Fn fopen
244 function
245 may also fail and set
246 .Va errno
247 for any of the errors specified for the routine
248 .Xr open 2 .
249 .Pp
250 The
251 .Fn fdopen
252 function
253 may also fail and set
254 .Va errno
255 for any of the errors specified for the routine
256 .Xr fcntl 2 .
257 .Pp
258 The
259 .Fn freopen
260 function
261 may also fail and set
262 .Va errno
263 for any of the errors specified for the routines
264 .Xr open 2 ,
265 .Xr fclose 3
266 and
267 .Xr fflush 3 .
268 .Sh SEE ALSO
269 .Xr open 2 ,
270 .Xr fclose 3 ,
271 .Xr fileno 3 ,
272 .Xr fseek 3 ,
273 .Xr funopen 3
274 .Sh STANDARDS
275 The
276 .Fn fopen
277 and
278 .Fn freopen
279 functions
280 conform to
281 .St -isoC-2011 .
282 The
283 .Fn fdopen
284 function
285 conforms to
286 .St -p1003.1-88 .