fopen, freopen, fdopen - Open a stream
#include <stdio.h>
FILE *fopen(
const char *path,
const char *mode ); FILE *fdopen(
int filedes,
const char *mode ); FILE *freopen(
const char *path,
const char *mode,
FILE *stream );
Standard C Library (libc)
Interfaces documented on this reference page conform to
industry standards as follows:
fopen(), freopen(): ISO C, XSH4.0, XSH4.2, XSH5.0
fdopen(): XSH4.0, XSH4.2, XSH5.0
Refer to the standards(5) reference page for more information
about industry standards and associated tags.
Points to a character string that contains the name of the
file to be opened. If the final component of the path
parameter specifies a symbolic link, the link is traversed
and pathname resolution continues. Points to a character
string that controls whether the file is opened for reading
(r), writing (w), or appending (a) and whether the
file is opened for updating (+). The mode can also include
a b parameter, but this is ignored (see DESCRIPTION).
Specifies the input stream. Specifies a valid open file
descriptor.
The fopen() function opens the file named by the path
parameter and associates a stream with it, returning a
pointer to the FILE structure of this stream.
The mode parameter controls the access allowed to the
stream. The parameter can have one of the following values.
In this list of values, the b character indicates a
binary file. UNIX systems do not distinguish between
binary and text files in the context of opening a stream,
and the b character is therefore ignored. However, the b
character is included in X/Open standards for alignment
with ISO C syntax that can apply to other kinds of operating
systems. Opens the file for reading. Creates a new
file for writing, or opens and truncates a file to zero
length. (The file is not truncated under the fdopen()
function.) Appends (opens a file for writing at the end
of the file, or creates a file for writing). Opens a file
for update (reading and writing). Truncates to zero
length or creates a file for update. (The file is not
truncated under the fdopen() function.) Appends (opens a
file for update, writing at the end of the file, or creates
a file for writing).
When you open a file for update, you can perform both
input and output operations on the resulting stream. However,
an output operation cannot be directly followed by
an input operation without an intervening call to the
fflush() function or a file-positioning operation
(fseek(), fsetpos(), or rewind() function). Also, an input
operation cannot be directly followed by an output operation
without an intervening flush or file positioning
operation, unless the input operation encounters the end
of the file.
When you open a file for append (that is, when the mode
parameter is a or a+), it is impossible to overwrite
information already in the file. You can use the fseek()
function to reposition the file pointer to any position in
the file, but when output is written to the file, the current
file pointer is ignored. All output is written at the
end of the file and the file pointer is repositioned to
the end of the output.
[Tru64 UNIX] If two separate processes open the same file
for append, each process can write freely to the file
without destroying the output being written by the other.
The output from the two processes is intermixed in the
order in which it is written to the file. Note that if the
data is buffered, it is not actually written until it is
flushed.
When opened, a stream is fully buffered if and only if it
can be determined that it does not refer to an interactive
device. The error and End-of-File indicators for the
stream are cleared.
If the mode parameter is w, a, w+, or a+ and the file did
not previously exist, upon successful completion the
fopen() function marks the st_atime, st_ctime and st_mtime
fields of the file and the st_ctime and st_mtime fields of
the parent directory for update. If the mode parameter is
w or w+ and the file did previously exist, upon successful
completion the fopen() function marks the st_ctime and
st_mtime fields of the file for update.
The freopen() function substitutes the named file in place
of the open stream. The original stream is closed regardless
of whether the open() function succeeds with the
named file. The freopen() function returns a pointer to
the FILE structure associated with the stream parameter.
The freopen() function is typically used to attach the
preopened streams associated with stdin, stdout, and
stderr to other files. The function uses the mode argument
in the same way as described for fopen().
The fdopen() function associates a stream with a file
descriptor obtained from an open(), dup(), creat(), or
pipe() function. These functions open files, but do not
return pointers to FILE structures. Many of the standard
I/O package functions require pointers to FILE structures.
Note that the mode of the stream specified must agree with
the mode of the open file. The meaning of mode values is
the same as described for fopen(), except that for
fdopen(), the values beginning with w do not cause truncation
of the file.
The fdopen() function sets the file position indicator
associated with the new stream to the position indicated
by the file offset associated with the file descriptor.
The function also clears the error and End-of-File indicators
for the stream.
Stream Orientation [Toc] [Back]
[ISO C] The current version of the ISO C standard specifies
that streams have an orientation: unbounded immediately
after the stream is opened, byte oriented if operated
on by a byte-oriented I/O function, and wide-character
oriented if operated on by a wide-character I/O function.
Furthermore, the standard defines the fwide() function
for explicitly querying stream orientation and, if
preceded by a call to freopen(), for changing stream orientation
without actually operating on the stream (see
fwide(3)). The reasons for these additions to the standard
are as follows. Both I/O functions that are byte oriented
and those that are wide-character oriented can refer to
the same FILE object. For wide-character functions, the
FILE object is assumed to include an mb_state object to
keep track of conversion-state information that currently
applies to the stream. Wide-character functions are
designed with the assumption that they always begin execution
with the stream positioned at the boundary between
two multibyte characters. The conversion-state information
in the mb_state object is needed for correct positioning
when an application executes in a locale that supports
shift-state encoding. While wide-character functions can
maintain consistency between the conversion state and the
stream, byte-oriented functions cannot. Therefore, a widecharacter
function cannot be assured of correct boundary
positioning in an open stream if that same stream is also
operated on by a byte-oriented function. The additions to
the ISO C standard allow application developers a way to
make sure that a stream opened by another function has the
correct orientation (either unbounded or wide-character)
before its associated FILE object is referred to by a
wide-character function.
Currently, Tru64 UNIX systems do not provide locales that
support shift-state encoding. Therefore, the ISO C rules
and definitions related to shift-state encoding and stream
orientation have no practical use when applications run on
Tru64 UNIX systems. However, these rules and definitions
are included for your convenience in using Tru64 UNIX to
develop applications that run on multiple platforms, some
of which may support locales with shift-state encoding.
On successful completion, the fopen(), fdopen(), and freopen()
functions return a pointer to the FILE object controlling
the stream.
If these functions fail, they return a null pointer and
set errno to indicate the error.
The fopen(), fdopen(), and freopen() functions set errno
to the specified values for the following conditions:
Search permission is denied on a component of the pathname
prefix; or the file exists and the permissions specified
by the mode parameter are denied; or the file does not
exist and write permission is denied for the parent
directory of the file to be created (fopen() or freopen()).
The filedes parameter is not a valid file
descriptor (fdopen() only). The function (fopen() or freopen())
was interrupted by a signal that was caught. The
mode parameter is not a valid mode. The named file is a
directory and mode requires write access (fopen() or freopen()).
Too many links were encountered in translating
path. OPEN_MAX file descriptors are currently open in the
calling process (freopen()).
[Tru64 UNIX] Either the OPEN_MAX value or the perprocess
soft descriptor limit is checked.
The FOPEN_MAX or STREAM_MAX streams are currently
open in the calling process (fopen() or fdopen()).
The length of the path string exceeds PATH_MAX or a
pathname component is longer than NAME_MAX (fopen()
or freopen()). Too many files are currently open
in the system (fopen() or freopen()). The named
file does not exist or the path parameter points to
an empty string (fopen() or freopen()). There is
insufficient space to allocate a buffer. The
directory or file system that would contain the new
file cannot be expanded (fopen() or freopen()). A
component of the pathname prefix is not a directory
(fopen() or freopen()). The named file is a character-special
or block-special file and the device
associated with this special file does not exist
(fopen() or freopen()). [Tru64 UNIX] The named
file is a socket bound to the file system (a UNIX
domain socket) and cannot be opened. The named
file resides on a read-only file system and mode
requires write access (fopen() or freopen()). The
file is being executed and the mode requires write
access (fopen() or freopen()).
Functions: open(2), fclose(3), fseek(3), fwide(3), setbuf(3), setlocale(3)
Standards: standards(5)
Network Programmer's Guide
fopen(3)
[ Back ] |
