'\" te
.\" Copyright (c) 2007 Sun Microsystems, Inc. All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
.\"  See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with
.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH FOPEN 3UCB "Oct 30, 2007"
.SH NAME
fopen, freopen \- open a stream
.SH SYNOPSIS
.LP
.nf
\fB/usr/ucb/cc\fR [ \fIflag\fR ... ] \fIfile\fR ...
#include <stdio.h>

\fBFILE *\fR\fBfopen\fR(\fIfile\fR, \fImode\fR)
\fBconst char *\fR\fIfile\fR, \fB*\fR\fImode\fR;
.fi

.LP
.nf
\fBFILE *\fR\fBfreopen\fR(\fIfile\fR, \fImode\fR, \fIiop\fR)
\fBconst char *\fR\fIfile\fR, \fB*\fR\fImode\fR;
\fBregister FILE *\fR\fIiop\fR;
.fi

.SH DESCRIPTION
.sp
.LP
The \fBfopen()\fR function opens the file specified by \fIfile\fR and
associates a stream with it. If the open succeeds, \fBfopen()\fR returns a
pointer to be used to identify the stream in subsequent operations. The
\fIfile\fR argument points to a character string that contains the name of the
file to be opened. The \fImode\fR argument is a character string having one of
the following values:
.sp
.ne 2
.na
\fB\fBr\fR\fR
.ad
.RS 6n
open for reading
.RE

.sp
.ne 2
.na
\fB\fBw\fR\fR
.ad
.RS 6n
truncate or create for writing
.RE

.sp
.ne 2
.na
\fB\fBa\fR\fR
.ad
.RS 6n
append: open for writing at end of file, or create for writing
.RE

.sp
.ne 2
.na
\fB\fBr+\fR\fR
.ad
.RS 6n
open for update (reading and writing)
.RE

.sp
.ne 2
.na
\fB\fBw+\fR\fR
.ad
.RS 6n
truncate or create for update
.RE

.sp
.ne 2
.na
\fB\fBa+\fR\fR
.ad
.RS 6n
append; open or create for update at \fBEOF\fR
.RE

.sp
.LP
The \fBfreopen()\fR function opens the file specified by \fIfile\fR and
associates the stream pointed to by \fIiop\fR with it. The \fImode\fR argument
is used just as in \fBfopen()\fR. The original stream is closed, regardless of
whether the open ultimately succeeds. If the open succeeds, \fBfreopen()\fR
returns the original value of \fIiop\fR.
.sp
.LP
The \fBfreopen()\fR function is typically used to attach the pre-opened streams
associated with\fBstdin\fR, \fBstdout\fR, and \fBstderr\fR to other files.
.sp
.LP
When a file is opened for update, both input and output can be performed on the
resulting stream. Output cannot be directly followed by input without an
intervening \fBfseek\fR(3C) or \fBrewind\fR(3C). Input cannot be directly
followed by output without an intervening \fBfseek\fR(3C) or \fBrewind\fR(3C).
An input operation that encounters  \fBEOF will fail.\fR
.SH RETURN VALUES
.sp
.LP
The \fBfopen()\fR and \fBfreopen()\fR functions return a \fINULL\fR pointer on
failure.
.SH USAGE
.sp
.LP
The \fBfopen()\fR and \fBfreopen()\fR functions have transitional interfaces
for 64-bit file offsets.  See \fBlf64\fR(5).
.SH SEE ALSO
.sp
.LP
\fBopen\fR(2), \fBfclose\fR(3C), \fBfopen\fR(3C), \fBfreopen\fR(3C),
\fBfseek\fR(3C), \fBmalloc\fR(3C), \fBrewind\fR(3C), \fBlf64\fR(5)
.SH NOTES
.sp
.LP
Use of these functions should be restricted to applications written on BSD
platforms.  Use of these functions with any of the system libraries or in
multithreaded applications is unsupported.
.sp
.LP
To support the same number of open files as the system, \fBfopen()\fR must
allocate additional memory for data structures using \fBmalloc\fR(3C) after 64
files have been opened. This confuses some programs that use their own memory
allocators.
.sp
.LP
The \fBfopen()\fR and  \fBfreopen()\fR functions differ from the standard I/O
functions \fBfopen\fR(3C) and \fBfreopen\fR(3C). The standard I/O functions
distinguish binary from text files with an additional use of '\fBb\fR' as part
of the \fImode\fR, enabling portability of \fBfopen\fR(3C) and
\fBfreopen\fR(3C) beyond SunOS  4.\fIx\fR systems.