b6cbf7203b
This patch imports the unmodified current version of NetBSD libc. The NetBSD includes are in /nbsd_include, while the libc code itself is split between lib/nbsd_libc and common/lib/libc.
279 lines
6.6 KiB
Groff
279 lines
6.6 KiB
Groff
.\" $NetBSD: fopen.3,v 1.24 2010/04/05 21:34:47 joerg 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 June 4, 1993
|
|
.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 indent
|
|
.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.
|
|
.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.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fa mode
|
|
string can also include the letter ``b'' 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 ``b'' is ignored.
|
|
.Pp
|
|
The letter ``f'' in the mode string restricts fopen to regular
|
|
files; if the file opened is not a regular file,
|
|
.Fn fopen
|
|
will fail.
|
|
This is a non
|
|
.St -ansiC
|
|
extension.
|
|
.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
|
|
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
|
|
.Bl -tag -width Er
|
|
.It Bq Er EINVAL
|
|
The
|
|
.Fa mode
|
|
provided to
|
|
.Fn fopen ,
|
|
.Fn fdopen ,
|
|
or
|
|
.Fn freopen
|
|
was invalid.
|
|
.It Bq Er EFTYPE
|
|
The file is not a regular file and the character ``f'' is specified
|
|
in the mode.
|
|
.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 .
|
|
The
|
|
.Fn fdopen
|
|
function conforms to
|
|
.St -p1003.1-90 .
|
|
.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
|