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.\" 4. 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
| 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.\" 4. 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: head/lib/libc/stdio/fopen.3 242460 2012-11-01 22:47:42Z jilles $
| 33.\" $FreeBSD: head/lib/libc/stdio/fopen.3 243731 2012-11-30 23:51:33Z jilles $
|
34.\"
| 34.\"
|
35.Dd October 17, 2011
| 35.Dd November 30, 2012
|
36.Dt FOPEN 3
37.Os
38.Sh NAME
39.Nm fopen ,
40.Nm fdopen ,
41.Nm freopen
42.Nd stream open functions
43.Sh LIBRARY
44.Lb libc
45.Sh SYNOPSIS
46.In stdio.h
47.Ft FILE *
48.Fn fopen "const char * restrict path" "const char * restrict mode"
49.Ft FILE *
50.Fn fdopen "int fildes" "const char *mode"
51.Ft FILE *
52.Fn freopen "const char *path" "const char *mode" "FILE *stream"
53.Sh DESCRIPTION
54The
55.Fn fopen
56function
57opens the file whose name is the string pointed to by
58.Fa path
59and associates a stream with it.
60.Pp
61The argument
62.Fa mode
63points to a string beginning with one of the following letters:
64.Bl -tag -width indent
65.It Dq Li r
66Open for reading.
67The stream is positioned at the beginning of the file.
68Fail if the file does not exist.
69.It Dq Li w
70Open for writing.
71The stream is positioned at the beginning of the file.
72Create the file if it does not exist.
73.It Dq Li a
74Open for writing.
75The stream is positioned at the end of the file.
76Subsequent writes to the file will always end up at the then current
77end of file, irrespective of any intervening
78.Xr fseek 3
79or similar.
80Create the file if it does not exist.
81.El
82.Pp
83An optional
84.Dq Li +
85following
86.Dq Li r ,
87.Dq Li w ,
88or
89.Dq Li a
90opens the file for both reading and writing.
91An optional
92.Dq Li x
93following
94.Dq Li w
95or
96.Dq Li w+
97causes the
98.Fn fopen
99call to fail if the file already exists.
| 36.Dt FOPEN 3
37.Os
38.Sh NAME
39.Nm fopen ,
40.Nm fdopen ,
41.Nm freopen
42.Nd stream open functions
43.Sh LIBRARY
44.Lb libc
45.Sh SYNOPSIS
46.In stdio.h
47.Ft FILE *
48.Fn fopen "const char * restrict path" "const char * restrict mode"
49.Ft FILE *
50.Fn fdopen "int fildes" "const char *mode"
51.Ft FILE *
52.Fn freopen "const char *path" "const char *mode" "FILE *stream"
53.Sh DESCRIPTION
54The
55.Fn fopen
56function
57opens the file whose name is the string pointed to by
58.Fa path
59and associates a stream with it.
60.Pp
61The argument
62.Fa mode
63points to a string beginning with one of the following letters:
64.Bl -tag -width indent
65.It Dq Li r
66Open for reading.
67The stream is positioned at the beginning of the file.
68Fail if the file does not exist.
69.It Dq Li w
70Open for writing.
71The stream is positioned at the beginning of the file.
72Create the file if it does not exist.
73.It Dq Li a
74Open for writing.
75The stream is positioned at the end of the file.
76Subsequent writes to the file will always end up at the then current
77end of file, irrespective of any intervening
78.Xr fseek 3
79or similar.
80Create the file if it does not exist.
81.El
82.Pp
83An optional
84.Dq Li +
85following
86.Dq Li r ,
87.Dq Li w ,
88or
89.Dq Li a
90opens the file for both reading and writing.
91An optional
92.Dq Li x
93following
94.Dq Li w
95or
96.Dq Li w+
97causes the
98.Fn fopen
99call to fail if the file already exists.
|
| 100An optional
101.Dq Li e
102following the above
103causes the
104.Fn fopen
105call to set the
106.Dv FD_CLOEXEC
107flag on the underlying file descriptor.
|
100.Pp
101The
102.Fa mode
103string can also include the letter
104.Dq Li b
105after either the
106.Dq Li +
107or the first letter.
108This is strictly for compatibility with
109.St -isoC
110and has no effect; the ``b'' is ignored.
111.Pp
112Any created files will have mode
113.Do Dv S_IRUSR
114\&|
115.Dv S_IWUSR
116\&|
117.Dv S_IRGRP
118\&|
119.Dv S_IWGRP
120\&|
121.Dv S_IROTH
122\&|
123.Dv S_IWOTH Dc
124.Pq Li 0666 ,
125as modified by the process'
126umask value (see
127.Xr umask 2 ) .
128.Pp
129Reads and writes may be intermixed on read/write streams in any order,
130and do not require an intermediate seek as in previous versions of
131.Em stdio .
132This is not portable to other systems, however;
133.Tn ANSI C
134requires that
135a file positioning function intervene between output and input, unless
136an input operation encounters end-of-file.
137.Pp
138The
139.Fn fdopen
140function associates a stream with the existing file descriptor,
141.Fa fildes .
142The mode
143of the stream must be compatible with the mode of the file descriptor.
144The
145.Dq Li x
146mode option is ignored.
| 108.Pp
109The
110.Fa mode
111string can also include the letter
112.Dq Li b
113after either the
114.Dq Li +
115or the first letter.
116This is strictly for compatibility with
117.St -isoC
118and has no effect; the ``b'' is ignored.
119.Pp
120Any created files will have mode
121.Do Dv S_IRUSR
122\&|
123.Dv S_IWUSR
124\&|
125.Dv S_IRGRP
126\&|
127.Dv S_IWGRP
128\&|
129.Dv S_IROTH
130\&|
131.Dv S_IWOTH Dc
132.Pq Li 0666 ,
133as modified by the process'
134umask value (see
135.Xr umask 2 ) .
136.Pp
137Reads and writes may be intermixed on read/write streams in any order,
138and do not require an intermediate seek as in previous versions of
139.Em stdio .
140This is not portable to other systems, however;
141.Tn ANSI C
142requires that
143a file positioning function intervene between output and input, unless
144an input operation encounters end-of-file.
145.Pp
146The
147.Fn fdopen
148function associates a stream with the existing file descriptor,
149.Fa fildes .
150The mode
151of the stream must be compatible with the mode of the file descriptor.
152The
153.Dq Li x
154mode option is ignored.
|
| 155If the
156.Dq Li e
157mode option is present, the
158.Dv FD_CLOEXEC
159flag is set, otherwise it remains unchanged.
|
147When the stream is closed via
148.Xr fclose 3 ,
149.Fa fildes
150is closed also.
151.Pp
152The
153.Fn freopen
154function
155opens the file whose name is the string pointed to by
156.Fa path
157and associates the stream pointed to by
158.Fa stream
159with it.
160The original stream (if it exists) is closed.
161The
162.Fa mode
163argument is used just as in the
164.Fn fopen
165function.
166.Pp
167If the
168.Fa path
169argument is
170.Dv NULL ,
171.Fn freopen
172attempts to re-open the file associated with
173.Fa stream
174with a new mode.
175The new mode must be compatible with the mode that the stream was originally
176opened with:
177Streams open for reading can only be re-opened for reading,
178streams open for writing can only be re-opened for writing,
179and streams open for reading and writing can be re-opened in any mode.
180The
181.Dq Li x
182mode option is not meaningful in this context.
183.Pp
184The primary use of the
185.Fn freopen
186function
187is to change the file associated with a
188standard text stream
189.Dv ( stderr , stdin ,
190or
191.Dv stdout ) .
192.Sh RETURN VALUES
193Upon successful completion
194.Fn fopen ,
195.Fn fdopen
196and
197.Fn freopen
198return a
199.Tn FILE
200pointer.
201Otherwise,
202.Dv NULL
203is returned and the global variable
204.Va errno
205is set to indicate the error.
206.Sh ERRORS
207.Bl -tag -width Er
208.It Bq Er EINVAL
209The
210.Fa mode
211argument
212to
213.Fn fopen ,
214.Fn fdopen ,
215or
216.Fn freopen
217was invalid.
218.El
219.Pp
220The
221.Fn fopen ,
222.Fn fdopen
223and
224.Fn freopen
225functions
226may also fail and set
227.Va errno
228for any of the errors specified for the routine
229.Xr malloc 3 .
230.Pp
231The
232.Fn fopen
233function
234may also fail and set
235.Va errno
236for any of the errors specified for the routine
237.Xr open 2 .
238.Pp
239The
240.Fn fdopen
241function
242may also fail and set
243.Va errno
244for any of the errors specified for the routine
245.Xr fcntl 2 .
246.Pp
247The
248.Fn freopen
249function
250may also fail and set
251.Va errno
252for any of the errors specified for the routines
253.Xr open 2 ,
254.Xr fclose 3
255and
256.Xr fflush 3 .
257.Sh SEE ALSO
258.Xr open 2 ,
259.Xr fclose 3 ,
260.Xr fileno 3 ,
261.Xr fseek 3 ,
262.Xr funopen 3
263.Sh STANDARDS
264The
265.Fn fopen
266and
267.Fn freopen
268functions
269conform to
270.St -isoC ,
271with the exception of the
272.Dq Li x
273mode option which conforms to
274.St -isoC-2011 .
275The
276.Fn fdopen
277function
278conforms to
279.St -p1003.1-88 .
| 160When the stream is closed via
161.Xr fclose 3 ,
162.Fa fildes
163is closed also.
164.Pp
165The
166.Fn freopen
167function
168opens the file whose name is the string pointed to by
169.Fa path
170and associates the stream pointed to by
171.Fa stream
172with it.
173The original stream (if it exists) is closed.
174The
175.Fa mode
176argument is used just as in the
177.Fn fopen
178function.
179.Pp
180If the
181.Fa path
182argument is
183.Dv NULL ,
184.Fn freopen
185attempts to re-open the file associated with
186.Fa stream
187with a new mode.
188The new mode must be compatible with the mode that the stream was originally
189opened with:
190Streams open for reading can only be re-opened for reading,
191streams open for writing can only be re-opened for writing,
192and streams open for reading and writing can be re-opened in any mode.
193The
194.Dq Li x
195mode option is not meaningful in this context.
196.Pp
197The primary use of the
198.Fn freopen
199function
200is to change the file associated with a
201standard text stream
202.Dv ( stderr , stdin ,
203or
204.Dv stdout ) .
205.Sh RETURN VALUES
206Upon successful completion
207.Fn fopen ,
208.Fn fdopen
209and
210.Fn freopen
211return a
212.Tn FILE
213pointer.
214Otherwise,
215.Dv NULL
216is returned and the global variable
217.Va errno
218is set to indicate the error.
219.Sh ERRORS
220.Bl -tag -width Er
221.It Bq Er EINVAL
222The
223.Fa mode
224argument
225to
226.Fn fopen ,
227.Fn fdopen ,
228or
229.Fn freopen
230was invalid.
231.El
232.Pp
233The
234.Fn fopen ,
235.Fn fdopen
236and
237.Fn freopen
238functions
239may also fail and set
240.Va errno
241for any of the errors specified for the routine
242.Xr malloc 3 .
243.Pp
244The
245.Fn fopen
246function
247may also fail and set
248.Va errno
249for any of the errors specified for the routine
250.Xr open 2 .
251.Pp
252The
253.Fn fdopen
254function
255may also fail and set
256.Va errno
257for any of the errors specified for the routine
258.Xr fcntl 2 .
259.Pp
260The
261.Fn freopen
262function
263may also fail and set
264.Va errno
265for any of the errors specified for the routines
266.Xr open 2 ,
267.Xr fclose 3
268and
269.Xr fflush 3 .
270.Sh SEE ALSO
271.Xr open 2 ,
272.Xr fclose 3 ,
273.Xr fileno 3 ,
274.Xr fseek 3 ,
275.Xr funopen 3
276.Sh STANDARDS
277The
278.Fn fopen
279and
280.Fn freopen
281functions
282conform to
283.St -isoC ,
284with the exception of the
285.Dq Li x
286mode option which conforms to
287.St -isoC-2011 .
288The
289.Fn fdopen
290function
291conforms to
292.St -p1003.1-88 .
|
| 293The
294.Dq Li e
295mode option does not conform to any standard
296but is also supported by glibc.
|
| |