[apple/libc.git] / stdio / FreeBSD / fopen.3

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