Standard C Library Functions fopen(3C)
NAME
fopen - open a stream
SYNOPSIS
#include
FILE *fopen(const char *filename, const char *mode);
DESCRIPTION
The fopen() function opens the file whose pathname is the
string pointed to by filename, and associates a stream with
it.
The argument mode points to a string beginning with one of
the following sequences:
r or rb Open file for reading.
w or wb Truncate to zero length or create file
for writing.
a or ab Append; open or create file for writing
at end-of-file.
r] or rb] or r]b Open file for update (reading and writ-
ing).
w] or wb] or w]b Truncate to zero length or create file
for update.
a] or ab] or a]b Append; open or create file for update,
writing at end-of-file.
The character b has no effect, but is allowed for ISO C
standard conformance (see standards(5)). Opening a file with
read mode (r as the first character in the mode argument)
fails if the file does not exist or cannot be read.
Opening a file with append mode (a as the first character in
the mode argument) causes all subsequent writes to the file
to be forced to the then current end-of-file, regardless of
intervening calls to fseek(3C). If two separate processes
SunOS 5.11 Last change: 18 Apr 2006 1
Standard C Library Functions fopen(3C)
open the same file for append, each process may write freely
to the file without fear of destroying output being written
by the other. The output from the two processes will be
intermixed in the file in the order in which it is written.
When a file is opened with update mode (] as the second or
third character in the mode argument), both input and output
may be performed on the associated stream. However, output
must not be directly followed by input without an interven-
ing call to fflush(3C) or to a file positioning function (
fseek(3C), fsetpos(3C) or rewind(3C)), and input must not be
directly followed by output without an intervening call to a
file positioning function, unless the input operation
encounters end-of-file.
When opened, a stream is fully buffered if and only if it
can be determined not to refer to an interactive device. The
error and end-of-file indicators for the stream are cleared.
If mode begins with w or a and the file did not previously
exist, upon successful completion, fopen() function will
mark for update the statime, stctime and stmtime fields
of the file and the stctime and stmtime fields of the
parent directory.
If mode begins with w and the file did previously exist,
upon successful completion, fopen() will mark for update the
stctime and stmtime fields of the file. The fopen() func-
tion will allocate a file descriptor as open(2) does.
Normally, 32-bit applications return an EMFILE error when
attempting to associate a stream with a file accessed by a
file descriptor with a value greater than 255. If the last
character of mode is F, 32-bit applications will be allowed
to associate a stream with a file accessed by a file
descriptor with a value greater than 255. A FILE pointer
obtained in this way must never be used by any code that
might directly access fields in the FILE structure. If the
fields in the FILE structure are used directly by 32-bit
applications when the last character of mode is F, data
corruption could occur. See the USAGE section of this manual
page and the enableextendedFILEstdio(3C) manual page for
other options for enabling the extended FILE facility.
In 64-bit applications, the last character of mode is
silently ignored if it is F. 64-bit applications are always
SunOS 5.11 Last change: 18 Apr 2006 2
Standard C Library Functions fopen(3C)
allowed to associate a stream with a file accessed by a file
descriptor with any value.
The largest value that can be represented correctly in an
object of type offt will be established as the offset max-
imum in the open file description.
RETURN VALUES
Upon successful completion, fopen() returns a pointer to the
object controlling the stream. Otherwise, a null pointer is
returned and errno is set to indicate the error.
The fopen() function may fail and not set errno if there are
no free stdio streams.
ERORS
The fopen() function will fail if:
EACES Search permission is denied on a component
of the path prefix, or the file exists and
the permissions specified by mode are
denied, or the file does not exist and write
permission is denied for the parent direc-
tory of the file to be created.
EINTR A signal was caught during the execution of
fopen().
EISDIR The named file is a directory and mode
requires write access.
ELOP Too many symbolic links were encountered in
resolving path.
EMFILE There are {OPENMAX} file descriptors
currently open in the calling process.
ENAMETOLONG The length of the filename exceeds PATHMAX
or a pathname component is longer than
NAMEMAX.
ENFILE The maximum allowable number of files is
currently open in the system.
SunOS 5.11 Last change: 18 Apr 2006 3
Standard C Library Functions fopen(3C)
ENOENT A component of filename does not name an
existing file or filename is an empty
string.
ENOSPC The directory or file system that would con-
tain the new file cannot be expanded, the
file does not exist, and it was to be
created.
ENOTDIR A component of the path prefix is not a
directory.
ENXIO The named file is a character special or
block special file, and the device associ-
ated with this special file does not exist.
EOVERFLOW The current value of the file position can-
not be represented correctly in an object of
type fpost.
EROFS The named file resides on a read-only file
system and mode requires write access.
The fopen() function may fail if:
EINVAL The value of the mode argument is not valid.
EMFILE {FOPENMAX} streams are currently open in
the calling process.
{STREAMAX} streams are currently open in
the calling process.
ENAMETOLONG Pathname resolution of a symbolic link pro-
duced an intermediate result whose length
exceeds {PATHMAX}.
ENOMEM Insufficient storage space is available.
ETXTBSY The file is a pure procedure (shared text)
file that is being executed and mode
SunOS 5.11 Last change: 18 Apr 2006 4
Standard C Library Functions fopen(3C)
requires write access.
USAGE
A process is allowed to have at least {FOPENMAX} stdio
streams open at a time. For 32-bit applications, however,
the underlying ABIs formerly required that no file descrip-
tor used to access the file underlying a stdio stream have a
value greater than 255. To maintain binary compatibility
with earlier Solaris releases, this limit still constrains
32-bit applications. However, when a 32-bit application is
aware that no code that has access to the FILE pointer
returned by fopen() will use the FILE pointer to directly
access any fields in the FILE structure, the F character can
be used as the last character in the mode argument to cir-
cumvent this limit. Because it could lead to data corrup-
tion, the F character in mode must never be used when the
FILE pointer might later be used by binary code unknown to
the user. The F character in mode is intended to be used by
library functions that need a FILE pointer to access data to
process a user request, but do not need to pass the FILE
pointer back to the user. 32-bit applications that have been
inspected can use the extended FILE facility to circumvent
this limit if the inspection shows that no FILE pointers
will be used to directly access FILE structure contents.
The fopen() function has a transitional interface for 64-bit
file offsets. See lf64(5).
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability See below.
MT-Level MT-Safe
The F character in the mode argument is Evolving. In all
other respects this function is Standard.
SEE ALSO
enableextendedFILEstdio(3C), fclose(3C), fdopen(3C),
fflush(3C), freopen(3C), fsetpos(3C), rewind(3C),
SunOS 5.11 Last change: 18 Apr 2006 5
Standard C Library Functions fopen(3C)
attributes(5), lf64(5), standards(5)
SunOS 5.11 Last change: 18 Apr 2006 6
|
