diff options
Diffstat (limited to 'static/netbsd/man3/fopen.3')
| -rw-r--r-- | static/netbsd/man3/fopen.3 | 326 |
1 files changed, 326 insertions, 0 deletions
diff --git a/static/netbsd/man3/fopen.3 b/static/netbsd/man3/fopen.3 new file mode 100644 index 00000000..71fd3cf2 --- /dev/null +++ b/static/netbsd/man3/fopen.3 @@ -0,0 +1,326 @@ +.\" $NetBSD: fopen.3,v 1.36 2019/09/02 00:32:55 sevan Exp $ +.\" +.\" 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. 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 +.\" +.Dd September 2, 2019 +.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 * restrict path" "const char * restrict mode" "FILE * restrict 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, which may be followed by additional modifiers +as indicated below: +.Bl -tag -width 4n +.It Dq Li a +Append; open an existing or new file for writing in append mode. +The file is created if it does not exist. +.It Dq Li a+ +Open for reading and writing in append mode. +The file is created if it does not exist. +.It Dq Li r +Read; open an existing file for reading. +.It Dq Li r+ +Open an existing file for reading and writing. +.It Dq Li w +Write; open an empty file for writing. +Truncate an existing file to zero length or create a new file. +.It Dq Li w+ +Open an empty file for reading and writing. +Truncate file to zero length or create file. +.El +.Pp +After one of those, the +.Fa mode +string can also include one or more of the following modifier letters: +.Bl -tag -width 4n +.It Sq b +The letter +.Sq b +may appear either as a 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 -ansiC , +where it means open in +.Dq binary +mode which is identical to text mode here, +so has no effect; the +.Sq b +is ignored. +.It Sq e +The letter +.Sq e +in the mode string sets the close-on-exec +.Pq Dv O_CLOEXEC +flag of the file descriptor, which means that it will not be available +after an +.Xr exec 3 +system call. +This is a non +.St -ansiC +extension. +.It Sq f +The letter +.Sq f +in the mode string restricts +.Fn fopen +to regular files; if the file opened is not a regular file, +.Fn fopen +will close it, and fail. +This is a non +.St -ansiC +extension. +.It Sq l +The letter +.Sq l +in the mode string turns the don't-follow-symlinks +.Pq Dv O_NOFOLLOW +flag of the file descriptor, which means that if the last path component +is a symbolic link, it will not be followed. +This is a non +.St -ansiC +extension. +.It Sq x +The letter +.Sq x +in the mode turns on exclusive open mode to the file +.Pq Dv O_EXCL +which means that the file will not be created if it already exists. +In that case +.Fn fopen +will fail. +.El +.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' +.Xr umask 2 +value. +.Pp +Opening a file with append mode causes all subsequent writes to it +to be forced to the then current end of file, regardless of intervening +repositioning of the stream. +.Pp +The +.Fn fopen +and +.Fn freopen +functions initially position the stream at the start of the file +unless the file is opened with append mode, +in which case the stream is initially positioned at the end of the file. +.\" PR 6072 claims this paragraph is not correct. +.\" .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 +.Fa mode +of the stream must be compatible with the mode of the file descriptor. +The stream is positioned at the file offset of the file descriptor. +.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. +The primary use of the +.Fn freopen +function +is to change the file associated with a +standard text stream +.Pf ( Em stderr , +.Em stdin , +or +.Em stdout ) . +.Pp +Input and output against the opened stream will be fully buffered, unless +it refers to an interactive terminal device, or a different kind of buffering +is specified in the environment. +See +.Xr setvbuf 3 +for additional details. +.Sh RETURN VALUES +Upon successful completion +.Fn fopen , +.Fn fdopen +and +.Fn freopen +return a FILE pointer. +Otherwise, +.Dv NULL +is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +The functions may fail if: +.Bl -tag -width Er +.It Bq Er EFTYPE +The file is not a regular file and the character ``f'' is specified +in the mode. +.It Bq Er EINVAL +The specified +.Fa mode +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 -ansiC . +All three functions are specified in +.St -p1003.1-2008 . +.Sh HISTORY +An +.Fn fopen +function appeared in +.At v1 . +.Sh CAVEATS +Proper code using +.Fn fdopen +with error checking should +.Xr close 2 +.Fa fildes +in case of failure, and +.Xr fclose 3 +the resulting FILE * in case of success. +.Bd -literal + FILE *file; + int fd; + + if ((file = fdopen(fd, "r")) != NULL) { + /* perform operations on the FILE * */ + fclose(file); + } else { + /* failure, report the error */ + close(fd); + } +.Ed |