-.\" Copyright (c) 1990 The Regents of the University of California.
+.\" Copyright (c) 1990, 1991 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
-.\" Chris Torek.
+.\" Chris Torek and the American National Standards Committee X3,
+.\" on Information Processing Systems.
.\"
-.\" %sccs.include.redist.man%
+.\" 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.
.\"
-.\" @(#)fopen.3 6.6 (Berkeley) %G%
+.\" 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.
.\"
-.TH FOPEN 3 ""
-.UC 7
-.SH NAME
-fopen, fdopen, freopen \- open a stream
-.SH SYNOPSIS
-.nf
-.ft B
-#include <stdio.h>
-
-FILE *
-fopen(char *path, char *type);
-
-FILE *
-fdopen(int fildes, char *type);
-
-FILE *
-freopen(char *path, char *type, FILE *stream);
-.ft R
-.fi
-.SH DESCRIPTION
-.I Fopen
-opens the file named by
-.I path
-and associates a stream with it, returning a pointer for identifying
-the stream in subsequent operations.
-.PP
-.I Type
-is one of the following character strings:
-.TP
-``r''
-Open for reading.
+.\" @(#)fopen.3 6.8 (Berkeley) 6/29/91
+.\"
+.Dd June 29, 1991
+.Dt FOPEN 3
+.Os
+.Sh NAME
+.Nm fopen ,
+.Nm fdopen ,
+.Nm freopen
+.Nd stream open functions
+.Sh SYNOPSIS
+.Fd #include <stdio.h>
+.Ft FILE *
+.Fn fopen "char *path" "char *mode"
+.Ft FILE *
+.Fn fdopen "int fildes" "char *mode"
+.Ft FILE *
+.Fn freopen "char *path" "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.
-.TP
-``r+''
+.It Dq Li r+
Open for reading and writing.
The stream is positioned at the beginning of the file.
-.TP
-``w''
-Open for writing.
-The file is created if it does not exist, otherwise it is truncated.
+.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.
-.TP
-``w+''
+.No 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.
-.TP
-``a''
+.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.
-.TP
-``a+''
+.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.
-.PP
+.El
+.Pp
The
-.I type
+.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 ANSI X3.159-1989 (``ANSI C'')
+This is strictly for compatibility with
+.St -ansiC
and has no effect; the ``b'' is ignored.
-.PP
-Any created files will have mode ``S_IRUSR | S_IWUSR | S_IRGRP |
-S_IWGRP | S_IROTH | S_IWOTH'' (0666), as modified by the process'
+.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
-.IR umask (2)).
-.PP
+.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
-stdio.
-This is not portable to other systems, however; ANSI C requires that
+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
-.I Fdopen
-associates a stream with a file descriptor obtained from
-.IR creat (2),
-.IR dup (2),
-.IR open (2),
-or
-.IR pipe (2).
+.Pp
The
-.I type
+.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.
-.PP
-.I Freopen
-substitutes the named file in place of the open
-.IR stream
-and returns a pointer to it.
-The original stream is closed.
-.I Freopen
-is typically used to attach the preopened constant names,
-.IR stdin ,
-.IR stdout ,
-and
-.I stderr
-to files.
-.SH "SEE ALSO"
-open(2), fclose(3), fseek(3), funopen(3)
-.SH "RETURN VALUES"
-Upon successful completion
-.IR fopen ,
-.I fdopen
+.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
+.Xr 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
-.I freopen
-return a FILE pointer.
-Otherwise, NULL is returned and the global variable
-.I errno
+.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
-.TP 15
-[EINVAL]
-The
-.I type
-provided to
-.IR fopen ,
-.IR fdopen ,
+.Sh ERRORS
+.Bl -tag -width [EINVAL]
+.It Bq Er EINVAL
+The
+.Fa mode
+provided to
+.Fn fopen ,
+.Fn fdopen ,
or
-.IR freopen
+.Fn freopen
was invalid.
-.PP
-.IR Fopen ,
-.I fdopen
+.El
+.Pp
+The
+.Fn fopen ,
+.Fn fdopen
and
-.I freopen
+.Fn freopen
+functions
may also fail and set
-.IR errno
+.Va errno
for any of the errors specified for the routine
-.IR malloc (3).
-.PP
-.I Fopen
+.Xr malloc 3 .
+.Pp
+The
+.Fn fopen
+function
may also fail and set
-.IR errno
+.Va errno
for any of the errors specified for the routine
-.IR open (2).
-.PP
-.I Fdopen
+.Xr open 2 .
+.Pp
+The
+.Fn fdopen
+function
may also fail and set
-.IR errno
+.Va errno
for any of the errors specified for the routine
-.IR fcntl (2).
-.PP
-.I Freopen
+.Xr fcntl 2 .
+.Pp
+The
+.Fn freopen
+function
may also fail and set
-.IR errno
+.Va errno
for any of the errors specified for the routines
-.IR open (2),
-.IR fclose (3)
+.Xr open 2 ,
+.Xr fclose 3
and
-.IR fflush (3).
-.SH STANDARDS
-.I Fopen
+.Xr fflush 3 .
+.Sh SEE ALSO
+.Xr open 2 ,
+.Xr fclose 3 ,
+.Xr fseek 3 ,
+.Xr funopen 3
+.Sh STANDARDS
+The
+.Fn fopen
and
-.I freopen
-conform to ANSI X3.159-1989 (``ANSI C'').
-.I Fdopen
-conforms to IEEE Std 1003.1-1988 (``POSIX'').
-.SH BUGS
-.I Fdopen
-may not be portable to systems other than UNIX.
+.Fn freopen
+functions
+conform to
+.St -ansiC .
+The
+.Fn fdopen
+function
+conforms to
+.St -p1003.1-88 .
projects / unix-history / blobdiff