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