 |
Index for
Section 3 |
|
 |
Alphabetical
listing for F |
|
 |
Bottom of
page |
|
fopen(3)
NAME
fopen, freopen, fdopen - Open a stream
SYNOPSIS
#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 );
LIBRARY
Standard C Library (libc)
STANDARDS
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.
PARAMETERS
path
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.
mode
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).
stream
Specifies the input stream.
filedes
Specifies a valid open file descriptor.
DESCRIPTION
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.
r or rb
Opens the file for reading.
w or wb
Creates a new file for writing, or opens and truncates a file to zero
length. (The file is not truncated under the fdopen() function.)
a or ab
Appends (opens a file for writing at the end of the file, or creates a
file for writing).
r+ or rb+ or r+b
Opens a file for update (reading and writing).
w+ or wb+ or w+b
Truncates to zero length or creates a file for update. (The file is not
truncated under the fdopen() function.)
a+ or ab+ or a+b
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
[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 wide-character 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.
RESTRICTIONS
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.
RETURN VALUES
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.
ERRORS
The fopen(), fdopen(), and freopen() functions set errno to the specified
values for the following conditions:
[EACCES]
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()).
[EBADF]
The filedes parameter is not a valid file descriptor (fdopen() only).
[EINTR]
The function (fopen() or freopen()) was interrupted by a signal that
was caught.
[EINVAL]
The mode parameter is not a valid mode.
[EISDIR]
The named file is a directory and mode requires write access (fopen()
or freopen()).
[ELOOP]
Too many links were encountered in translating path.
[EMFILE]
OPEN_MAX file descriptors are currently open in the calling process
(freopen()).
[Tru64 UNIX] Either the OPEN_MAX value or the per-process soft
descriptor limit is checked.
The FOPEN_MAX or STREAM_MAX streams are currently open in the calling
process (fopen() or fdopen()).
[ENAMETOOLONG]
The length of the path string exceeds PATH_MAX or a pathname component
is longer than NAME_MAX (fopen() or freopen()).
[ENFILE]
Too many files are currently open in the system (fopen() or freopen()).
[ENOENT]
The named file does not exist or the path parameter points to an empty
string (fopen() or freopen()).
[ENOMEM]
There is insufficient space to allocate a buffer.
[ENOSPC]
The directory or file system that would contain the new file cannot be
expanded (fopen() or freopen()).
[ENOTDIR]
A component of the pathname prefix is not a directory (fopen() or
freopen()).
[ENXIO]
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()).
[EOPNOTSUPP]
[Tru64 UNIX] The named file is a socket bound to the file system (a
UNIX domain socket) and cannot be opened.
[EROFS]
The named file resides on a read-only file system and mode requires
write access (fopen() or freopen()).
[ETXTBSY]
The file is being executed and the mode requires write access (fopen()
or freopen()).
SEE ALSO
Functions: open(2), fclose(3), fseek(3), fwide(3), setbuf(3), setlocale(3)
Standards: standards(5)
Network Programmer's Guide
|
Index for
Section 3 |
|
|
Alphabetical
listing for F |
|
 |
Top of
page |
|