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