f14fb60209
* Updating common/lib * Updating lib/csu * Updating lib/libc * Updating libexec/ld.elf_so * Corrected test on __minix in featuretest to actually follow the meaning of the comment. * Cleaned up _REENTRANT-related defintions. * Disabled -D_REENTRANT for libfetch * Removing some unneeded __NBSD_LIBC defines and tests Change-Id: Ic1394baef74d11b9f86b312f5ff4bbc3cbf72ce2
292 lines
6.8 KiB
Groff
292 lines
6.8 KiB
Groff
.\" $NetBSD: fopen.3,v 1.28 2012/07/02 20:02:43 wiz 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 July 18, 2011
|
|
.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 (Additional characters may follow these sequences.):
|
|
.Bl -tag -width 4n
|
|
.It Dq Li a
|
|
Append; open for writing.
|
|
The file is created if it does not exist.
|
|
.It Dq Li a+
|
|
Append; open for reading and writing.
|
|
The file is created if it does not exist.
|
|
.It Dq Li r
|
|
Open for reading.
|
|
.It Dq Li r+
|
|
Open for reading and writing.
|
|
.It Dq Li w
|
|
Open for writing.
|
|
Truncate file to zero length or create file.
|
|
.It Dq Li w+
|
|
Open for reading and writing.
|
|
Truncate file to zero length or create file.
|
|
.El
|
|
.Pp
|
|
Additionally, the
|
|
.Fa mode
|
|
string can also include one of the following 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
|
|
and has no effect; the
|
|
.Sq b
|
|
is ignored.
|
|
.It Sq e
|
|
The letter
|
|
.Sq e
|
|
in the mode string sets the close-on-exec flag in the file descriptors of
|
|
the newly opened file files; if the operation fails,
|
|
.Fn fopen
|
|
will fail.
|
|
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 fail.
|
|
This is a non
|
|
.St -ansiC
|
|
extension.
|
|
.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 ) .
|
|
.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
|
|
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 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
|