xref: /minix3/lib/libc/stdio/fopen.3 (revision 0a6a1f1d05b60e214de2f05a7310ddd1f0e590e7)
1*0a6a1f1dSLionel Sambuc.\"	$NetBSD: fopen.3,v 1.31 2015/07/15 19:08:43 christos Exp $
22fe8fb19SBen Gras.\"
32fe8fb19SBen Gras.\" Copyright (c) 1990, 1991, 1993
42fe8fb19SBen Gras.\"	The Regents of the University of California.  All rights reserved.
52fe8fb19SBen Gras.\"
62fe8fb19SBen Gras.\" This code is derived from software contributed to Berkeley by
72fe8fb19SBen Gras.\" Chris Torek and the American National Standards Committee X3,
82fe8fb19SBen Gras.\" on Information Processing Systems.
92fe8fb19SBen Gras.\"
102fe8fb19SBen Gras.\" Redistribution and use in source and binary forms, with or without
112fe8fb19SBen Gras.\" modification, are permitted provided that the following conditions
122fe8fb19SBen Gras.\" are met:
132fe8fb19SBen Gras.\" 1. Redistributions of source code must retain the above copyright
142fe8fb19SBen Gras.\"    notice, this list of conditions and the following disclaimer.
152fe8fb19SBen Gras.\" 2. Redistributions in binary form must reproduce the above copyright
162fe8fb19SBen Gras.\"    notice, this list of conditions and the following disclaimer in the
172fe8fb19SBen Gras.\"    documentation and/or other materials provided with the distribution.
182fe8fb19SBen Gras.\" 3. Neither the name of the University nor the names of its contributors
192fe8fb19SBen Gras.\"    may be used to endorse or promote products derived from this software
202fe8fb19SBen Gras.\"    without specific prior written permission.
212fe8fb19SBen Gras.\"
222fe8fb19SBen Gras.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
232fe8fb19SBen Gras.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
242fe8fb19SBen Gras.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
252fe8fb19SBen Gras.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
262fe8fb19SBen Gras.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
272fe8fb19SBen Gras.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
282fe8fb19SBen Gras.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
292fe8fb19SBen Gras.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
302fe8fb19SBen Gras.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
312fe8fb19SBen Gras.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
322fe8fb19SBen Gras.\" SUCH DAMAGE.
332fe8fb19SBen Gras.\"
342fe8fb19SBen Gras.\"     @(#)fopen.3	8.1 (Berkeley) 6/4/93
352fe8fb19SBen Gras.\"
3684d9c625SLionel Sambuc.Dd November 14, 2012
372fe8fb19SBen Gras.Dt FOPEN 3
382fe8fb19SBen Gras.Os
392fe8fb19SBen Gras.Sh NAME
402fe8fb19SBen Gras.Nm fopen ,
412fe8fb19SBen Gras.Nm fdopen ,
422fe8fb19SBen Gras.Nm freopen
432fe8fb19SBen Gras.Nd stream open functions
442fe8fb19SBen Gras.Sh LIBRARY
452fe8fb19SBen Gras.Lb libc
462fe8fb19SBen Gras.Sh SYNOPSIS
472fe8fb19SBen Gras.In stdio.h
482fe8fb19SBen Gras.Ft FILE *
492fe8fb19SBen Gras.Fn fopen "const char * restrict path" "const char * restrict mode"
502fe8fb19SBen Gras.Ft FILE *
512fe8fb19SBen Gras.Fn fdopen "int fildes" "const char *mode"
522fe8fb19SBen Gras.Ft FILE *
532fe8fb19SBen Gras.Fn freopen "const char * restrict path" "const char * restrict mode" "FILE * restrict stream"
542fe8fb19SBen Gras.Sh DESCRIPTION
552fe8fb19SBen GrasThe
562fe8fb19SBen Gras.Fn fopen
572fe8fb19SBen Grasfunction
582fe8fb19SBen Grasopens the file whose name is the string pointed to by
592fe8fb19SBen Gras.Fa path
602fe8fb19SBen Grasand associates a stream with it.
612fe8fb19SBen Gras.Pp
622fe8fb19SBen GrasThe argument
632fe8fb19SBen Gras.Fa mode
642fe8fb19SBen Graspoints to a string beginning with one of the following
652fe8fb19SBen Grassequences (Additional characters may follow these sequences.):
66f14fb602SLionel Sambuc.Bl -tag -width 4n
67f14fb602SLionel Sambuc.It Dq Li a
68f14fb602SLionel SambucAppend; open for writing.
69f14fb602SLionel SambucThe file is created if it does not exist.
70f14fb602SLionel Sambuc.It Dq Li a+
71f14fb602SLionel SambucAppend; open for reading and writing.
72f14fb602SLionel SambucThe file is created if it does not exist.
732fe8fb19SBen Gras.It Dq Li r
742fe8fb19SBen GrasOpen for reading.
752fe8fb19SBen Gras.It Dq Li r+
762fe8fb19SBen GrasOpen for reading and writing.
772fe8fb19SBen Gras.It Dq Li w
782fe8fb19SBen GrasOpen for writing.
792fe8fb19SBen GrasTruncate file to zero length or create file.
802fe8fb19SBen Gras.It Dq Li w+
812fe8fb19SBen GrasOpen for reading and writing.
822fe8fb19SBen GrasTruncate file to zero length or create file.
832fe8fb19SBen Gras.El
842fe8fb19SBen Gras.Pp
85f14fb602SLionel SambucAdditionally, the
862fe8fb19SBen Gras.Fa mode
87f14fb602SLionel Sambucstring can also include one of the following letters:
88f14fb602SLionel Sambuc.Bl -tag -width 4n
89f14fb602SLionel Sambuc.It Sq b
90f14fb602SLionel SambucThe letter
91f14fb602SLionel Sambuc.Sq b
92f14fb602SLionel Sambucmay appear either as a last character or as a character between the
93f14fb602SLionel Sambuccharacters in any of the two-character strings described above.
942fe8fb19SBen GrasThis is strictly for compatibility with
952fe8fb19SBen Gras.St -ansiC
96f14fb602SLionel Sambucand has no effect; the
97f14fb602SLionel Sambuc.Sq b
98f14fb602SLionel Sambucis ignored.
99f14fb602SLionel Sambuc.It Sq e
100f14fb602SLionel SambucThe letter
101f14fb602SLionel Sambuc.Sq e
102f14fb602SLionel Sambucin the mode string sets the close-on-exec flag in the file descriptors of
103f14fb602SLionel Sambucthe newly opened file files; if the operation fails,
1042fe8fb19SBen Gras.Fn fopen
1052fe8fb19SBen Graswill fail.
1062fe8fb19SBen GrasThis is a non
1072fe8fb19SBen Gras.St -ansiC
1082fe8fb19SBen Grasextension.
109f14fb602SLionel Sambuc.It Sq f
110f14fb602SLionel SambucThe letter
111f14fb602SLionel Sambuc.Sq f
112f14fb602SLionel Sambucin the mode string restricts
113f14fb602SLionel Sambuc.Fn fopen
114f14fb602SLionel Sambucto regular files; if the file opened is not a regular file,
115f14fb602SLionel Sambuc.Fn fopen
116f14fb602SLionel Sambucwill fail.
117f14fb602SLionel SambucThis is a non
118f14fb602SLionel Sambuc.St -ansiC
119f14fb602SLionel Sambucextension.
12084d9c625SLionel Sambuc.It Sq x
12184d9c625SLionel SambucThe letter
12284d9c625SLionel Sambuc.Sq x
123*0a6a1f1dSLionel Sambucin the mode turns on exclusive open mode to the file
124*0a6a1f1dSLionel Sambuc.Pq Dv O_EXCL
12584d9c625SLionel Sambucwhich means that the file will not be created if it already exists.
126f14fb602SLionel Sambuc.El
1272fe8fb19SBen Gras.Pp
1282fe8fb19SBen GrasAny created files will have mode
1292fe8fb19SBen Gras.Pf \*q Dv S_IRUSR
1302fe8fb19SBen Gras\&|
1312fe8fb19SBen Gras.Dv S_IWUSR
1322fe8fb19SBen Gras\&|
1332fe8fb19SBen Gras.Dv S_IRGRP
1342fe8fb19SBen Gras\&|
1352fe8fb19SBen Gras.Dv S_IWGRP
1362fe8fb19SBen Gras\&|
1372fe8fb19SBen Gras.Dv S_IROTH
1382fe8fb19SBen Gras\&|
1392fe8fb19SBen Gras.Dv S_IWOTH Ns \*q
1402fe8fb19SBen Gras.Pq Li 0666 ,
1412fe8fb19SBen Grasas modified by the process'
142f14fb602SLionel Sambuc.Xr umask 2
143f14fb602SLionel Sambucvalue.
1442fe8fb19SBen Gras.Pp
1452fe8fb19SBen GrasOpening a file with append mode causes all subsequent writes to it
1462fe8fb19SBen Grasto be forced to the then current end of file, regardless of intervening
1472fe8fb19SBen Grasrepositioning of the stream.
1482fe8fb19SBen Gras.Pp
1492fe8fb19SBen GrasThe
1502fe8fb19SBen Gras.Fn fopen
1512fe8fb19SBen Grasand
1522fe8fb19SBen Gras.Fn freopen
1532fe8fb19SBen Grasfunctions initially position the stream at the start of the file
1542fe8fb19SBen Grasunless the file is opened with append mode,
1552fe8fb19SBen Grasin which case the stream is initially positioned at the end of the file.
1562fe8fb19SBen Gras.\" PR 6072 claims this paragraph is not correct.
1572fe8fb19SBen Gras.\" .Pp
1582fe8fb19SBen Gras.\" Reads and writes may be intermixed on read/write streams in any order,
1592fe8fb19SBen Gras.\" and do not require an intermediate seek as in previous versions of
1602fe8fb19SBen Gras.\" .Em stdio .
1612fe8fb19SBen Gras.\" This is not portable to other systems, however;
1622fe8fb19SBen Gras.\" .Tn ANSI C
1632fe8fb19SBen Gras.\" requires that
1642fe8fb19SBen Gras.\" a file positioning function intervene between output and input, unless
1652fe8fb19SBen Gras.\" an input operation encounters end-of-file.
1662fe8fb19SBen Gras.Pp
1672fe8fb19SBen GrasThe
1682fe8fb19SBen Gras.Fn fdopen
1692fe8fb19SBen Grasfunction associates a stream with the existing file descriptor,
1702fe8fb19SBen Gras.Fa fildes .
1712fe8fb19SBen GrasThe
1722fe8fb19SBen Gras.Fa mode
1732fe8fb19SBen Grasof the stream must be compatible with the mode of the file descriptor.
1742fe8fb19SBen GrasThe stream is positioned at the file offset of the file descriptor.
1752fe8fb19SBen Gras.Pp
1762fe8fb19SBen GrasThe
1772fe8fb19SBen Gras.Fn freopen
1782fe8fb19SBen Grasfunction
1792fe8fb19SBen Grasopens the file whose name is the string pointed to by
1802fe8fb19SBen Gras.Fa path
1812fe8fb19SBen Grasand associates the stream pointed to by
1822fe8fb19SBen Gras.Fa stream
1832fe8fb19SBen Graswith it.
1842fe8fb19SBen GrasThe original stream (if it exists) is closed.
1852fe8fb19SBen GrasThe
1862fe8fb19SBen Gras.Fa mode
1872fe8fb19SBen Grasargument is used just as in the
1882fe8fb19SBen Gras.Fn fopen
1892fe8fb19SBen Grasfunction.
1902fe8fb19SBen GrasThe primary use of the
1912fe8fb19SBen Gras.Fn freopen
1922fe8fb19SBen Grasfunction
1932fe8fb19SBen Grasis to change the file associated with a
1942fe8fb19SBen Grasstandard text stream
1952fe8fb19SBen Gras.Pf ( Em stderr ,
1962fe8fb19SBen Gras.Em stdin ,
1972fe8fb19SBen Grasor
1982fe8fb19SBen Gras.Em stdout ) .
199*0a6a1f1dSLionel Sambuc.Pp
200*0a6a1f1dSLionel SambucInput and output against the opened stream will be fully buffered, unless
201*0a6a1f1dSLionel Sambucit refers to an interactive terminal device, or a different kind of buffering
202*0a6a1f1dSLionel Sambucis specified in the environment.
203*0a6a1f1dSLionel SambucSee
204*0a6a1f1dSLionel Sambuc.Xr setvbuf 3
205*0a6a1f1dSLionel Sambucfor additional details.
2062fe8fb19SBen Gras.Sh RETURN VALUES
2072fe8fb19SBen GrasUpon successful completion
2082fe8fb19SBen Gras.Fn fopen ,
2092fe8fb19SBen Gras.Fn fdopen
2102fe8fb19SBen Grasand
2112fe8fb19SBen Gras.Fn freopen
2122fe8fb19SBen Grasreturn a
2132fe8fb19SBen Gras.Tn FILE
2142fe8fb19SBen Graspointer.
2152fe8fb19SBen GrasOtherwise,
2162fe8fb19SBen Gras.Dv NULL
2172fe8fb19SBen Grasis returned and the global variable
2182fe8fb19SBen Gras.Va errno
2192fe8fb19SBen Grasis set to indicate the error.
2202fe8fb19SBen Gras.Sh ERRORS
221f14fb602SLionel SambucThe functions may fail if:
2222fe8fb19SBen Gras.Bl -tag -width Er
2232fe8fb19SBen Gras.It Bq Er EFTYPE
2242fe8fb19SBen GrasThe file is not a regular file and the character ``f'' is specified
2252fe8fb19SBen Grasin the mode.
226f14fb602SLionel Sambuc.It Bq Er EINVAL
227f14fb602SLionel SambucThe specified
228f14fb602SLionel Sambuc.Fa mode
229f14fb602SLionel Sambucwas invalid.
2302fe8fb19SBen Gras.El
2312fe8fb19SBen Gras.Pp
2322fe8fb19SBen GrasThe
2332fe8fb19SBen Gras.Fn fopen ,
2342fe8fb19SBen Gras.Fn fdopen
2352fe8fb19SBen Grasand
2362fe8fb19SBen Gras.Fn freopen
2372fe8fb19SBen Grasfunctions
2382fe8fb19SBen Grasmay also fail and set
2392fe8fb19SBen Gras.Va errno
2402fe8fb19SBen Grasfor any of the errors specified for the routine
2412fe8fb19SBen Gras.Xr malloc 3 .
2422fe8fb19SBen Gras.Pp
2432fe8fb19SBen GrasThe
2442fe8fb19SBen Gras.Fn fopen
2452fe8fb19SBen Grasfunction
2462fe8fb19SBen Grasmay also fail and set
2472fe8fb19SBen Gras.Va errno
2482fe8fb19SBen Grasfor any of the errors specified for the routine
2492fe8fb19SBen Gras.Xr open 2 .
2502fe8fb19SBen Gras.Pp
2512fe8fb19SBen GrasThe
2522fe8fb19SBen Gras.Fn fdopen
2532fe8fb19SBen Grasfunction
2542fe8fb19SBen Grasmay also fail and set
2552fe8fb19SBen Gras.Va errno
2562fe8fb19SBen Grasfor any of the errors specified for the routine
2572fe8fb19SBen Gras.Xr fcntl 2 .
2582fe8fb19SBen Gras.Pp
2592fe8fb19SBen GrasThe
2602fe8fb19SBen Gras.Fn freopen
2612fe8fb19SBen Grasfunction
2622fe8fb19SBen Grasmay also fail and set
2632fe8fb19SBen Gras.Va errno
2642fe8fb19SBen Grasfor any of the errors specified for the routines
2652fe8fb19SBen Gras.Xr open 2 ,
2662fe8fb19SBen Gras.Xr fclose 3
2672fe8fb19SBen Grasand
2682fe8fb19SBen Gras.Xr fflush 3 .
2692fe8fb19SBen Gras.Sh SEE ALSO
2702fe8fb19SBen Gras.Xr open 2 ,
2712fe8fb19SBen Gras.Xr fclose 3 ,
2722fe8fb19SBen Gras.Xr fileno 3 ,
2732fe8fb19SBen Gras.Xr fseek 3 ,
2742fe8fb19SBen Gras.Xr funopen 3
2752fe8fb19SBen Gras.Sh STANDARDS
2762fe8fb19SBen GrasThe
2772fe8fb19SBen Gras.Fn fopen
2782fe8fb19SBen Grasand
2792fe8fb19SBen Gras.Fn freopen
280f14fb602SLionel Sambucfunctions conform to
2812fe8fb19SBen Gras.St -ansiC .
282f14fb602SLionel SambucAll three functions are specified in
283f14fb602SLionel Sambuc.St -p1003.1-2008 .
2842fe8fb19SBen Gras.Sh CAVEATS
2852fe8fb19SBen GrasProper code using
2862fe8fb19SBen Gras.Fn fdopen
2872fe8fb19SBen Graswith error checking should
2882fe8fb19SBen Gras.Xr close 2
2892fe8fb19SBen Gras.Fa fildes
2902fe8fb19SBen Grasin case of failure, and
2912fe8fb19SBen Gras.Xr fclose 3
2922fe8fb19SBen Grasthe resulting FILE * in case of success.
2932fe8fb19SBen Gras.Bd -literal
2942fe8fb19SBen Gras	FILE *file;
2952fe8fb19SBen Gras	int fd;
2962fe8fb19SBen Gras
2972fe8fb19SBen Gras	if ((file = fdopen(fd, "r")) != NULL) {
2982fe8fb19SBen Gras		/* perform operations on the FILE * */
2992fe8fb19SBen Gras		fclose(file);
3002fe8fb19SBen Gras	} else {
3012fe8fb19SBen Gras		/* failure, report the error */
3022fe8fb19SBen Gras		close(fd);
3032fe8fb19SBen Gras	}
3042fe8fb19SBen Gras.Ed
305