xref: /freebsd/lib/libc/stdio/fopen.3 (revision af6a5351a1fdb1130f18be6c782c4d48916eb971)
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$
34.\"
35.Dd January 30, 2013
36.Dt FOPEN 3
37.Os
38.Sh NAME
39.Nm fopen ,
40.Nm fdopen ,
41.Nm freopen ,
42.Nm fmemopen
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.Ft FILE *
55.Fn fmemopen "void *restrict *buf" "size_t size" "const char * restrict mode"
56.Sh DESCRIPTION
57The
58.Fn fopen
59function
60opens the file whose name is the string pointed to by
61.Fa path
62and associates a stream with it.
63.Pp
64The argument
65.Fa mode
66points to a string beginning with one of the following letters:
67.Bl -tag -width indent
68.It Dq Li r
69Open for reading.
70The stream is positioned at the beginning of the file.
71Fail if the file does not exist.
72.It Dq Li w
73Open for writing.
74The stream is positioned at the beginning of the file.
75Create the file if it does not exist.
76.It Dq Li a
77Open for writing.
78The stream is positioned at the end of the file.
79Subsequent writes to the file will always end up at the then current
80end of file, irrespective of any intervening
81.Xr fseek 3
82or similar.
83Create the file if it does not exist.
84.El
85.Pp
86An optional
87.Dq Li +
88following
89.Dq Li r ,
90.Dq Li w ,
91or
92.Dq Li a
93opens the file for both reading and writing.
94An optional
95.Dq Li x
96following
97.Dq Li w
98or
99.Dq Li w+
100causes the
101.Fn fopen
102call to fail if the file already exists.
103An optional
104.Dq Li e
105following the above
106causes the
107.Fn fopen
108call to set the
109.Dv FD_CLOEXEC
110flag on the underlying file descriptor.
111.Pp
112The
113.Fa mode
114string can also include the letter
115.Dq Li b
116after either the
117.Dq Li +
118or the first letter.
119This is strictly for compatibility with
120.St -isoC
121and has effect only for
122.Fn fmemopen
123; otherwise
124.Dq Li b
125is ignored.
126.Pp
127Any created files will have mode
128.Do Dv S_IRUSR
129\&|
130.Dv S_IWUSR
131\&|
132.Dv S_IRGRP
133\&|
134.Dv S_IWGRP
135\&|
136.Dv S_IROTH
137\&|
138.Dv S_IWOTH Dc
139.Pq Li 0666 ,
140as modified by the process'
141umask value (see
142.Xr umask 2 ) .
143.Pp
144Reads and writes may be intermixed on read/write streams in any order,
145and do not require an intermediate seek as in previous versions of
146.Em stdio .
147This is not portable to other systems, however;
148.Tn ANSI C
149requires that
150a file positioning function intervene between output and input, unless
151an input operation encounters end-of-file.
152.Pp
153The
154.Fn fdopen
155function associates a stream with the existing file descriptor,
156.Fa fildes .
157The mode
158of the stream must be compatible with the mode of the file descriptor.
159The
160.Dq Li x
161mode option is ignored.
162If the
163.Dq Li e
164mode option is present, the
165.Dv FD_CLOEXEC
166flag is set, otherwise it remains unchanged.
167When the stream is closed via
168.Xr fclose 3 ,
169.Fa fildes
170is closed also.
171.Pp
172The
173.Fn freopen
174function
175opens the file whose name is the string pointed to by
176.Fa path
177and associates the stream pointed to by
178.Fa stream
179with it.
180The original stream (if it exists) is closed.
181The
182.Fa mode
183argument is used just as in the
184.Fn fopen
185function.
186.Pp
187If the
188.Fa path
189argument is
190.Dv NULL ,
191.Fn freopen
192attempts to re-open the file associated with
193.Fa stream
194with a new mode.
195The new mode must be compatible with the mode that the stream was originally
196opened with:
197Streams open for reading can only be re-opened for reading,
198streams open for writing can only be re-opened for writing,
199and streams open for reading and writing can be re-opened in any mode.
200The
201.Dq Li x
202mode option is not meaningful in this context.
203.Pp
204The primary use of the
205.Fn freopen
206function
207is to change the file associated with a
208standard text stream
209.Dv ( stderr , stdin ,
210or
211.Dv stdout ) .
212.Pp
213The
214.Fn fmemopen
215function
216associates the buffer given by the
217.Fa buf
218and
219.Fa size
220arguments with a stream.
221The
222.Fa buf
223argument is either a null pointer or point to a buffer that
224is at least
225.Fa size
226bytes long.
227If a null pointer is specified as the
228.Fa buf
229argument,
230.Fn fmemopen
231allocates
232.Fa size
233bytes of memory. This buffer is automatically freed when the
234stream is closed. Buffers can be opened in text-mode (default) or binary-mode
235(if
236.Dq Li b
237is present in the second or third position of the
238.Fa mode
239argument). Buffers opened in text-mode make sure that writes are terminated with
240a NULL byte, if the last write hasn't filled up the whole buffer. Buffers
241opened in binary-mode never append a NULL byte.
242.Sh RETURN VALUES
243Upon successful completion
244.Fn fopen ,
245.Fn fdopen
246and
247.Fn freopen
248return a
249.Tn FILE
250pointer.
251Otherwise,
252.Dv NULL
253is returned and the global variable
254.Va errno
255is set to indicate the error.
256.Sh ERRORS
257.Bl -tag -width Er
258.It Bq Er EINVAL
259The
260.Fa mode
261argument
262to
263.Fn fopen ,
264.Fn fdopen ,
265.Fn freopen ,
266or
267.Fn fmemopen
268was invalid.
269.El
270.Pp
271The
272.Fn fopen ,
273.Fn fdopen ,
274.Fn freopen
275and
276.Fn fmemopen
277functions
278may also fail and set
279.Va errno
280for any of the errors specified for the routine
281.Xr malloc 3 .
282.Pp
283The
284.Fn fopen
285function
286may also fail and set
287.Va errno
288for any of the errors specified for the routine
289.Xr open 2 .
290.Pp
291The
292.Fn fdopen
293function
294may also fail and set
295.Va errno
296for any of the errors specified for the routine
297.Xr fcntl 2 .
298.Pp
299The
300.Fn freopen
301function
302may also fail and set
303.Va errno
304for any of the errors specified for the routines
305.Xr open 2 ,
306.Xr fclose 3
307and
308.Xr fflush 3 .
309.Pp
310The
311.Fn fmemopen
312function
313may also fail and set
314.Va errno
315if the
316.Fa size
317argument is 0.
318.Sh SEE ALSO
319.Xr open 2 ,
320.Xr fclose 3 ,
321.Xr fileno 3 ,
322.Xr fseek 3 ,
323.Xr funopen 3
324.Sh STANDARDS
325The
326.Fn fopen
327and
328.Fn freopen
329functions
330conform to
331.St -isoC ,
332with the exception of the
333.Dq Li x
334mode option which conforms to
335.St -isoC-2011 .
336The
337.Fn fdopen
338function
339conforms to
340.St -p1003.1-88 .
341The
342.Dq Li e
343mode option does not conform to any standard
344but is also supported by glibc.
345The
346.Fn fmemopen
347function
348conforms to
349.St -p1003.1-2008 .
350The
351.Dq Li b
352mode does not conform to any standard
353but is also supported by glibc.
354