fopen
Standard I/O Functions fopen(3S)
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 _f_i_l_e_n_a_m_e, and associates a stream with
it.
The argument _m_o_d_e 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 writ-
ing.
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 writing).
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 _m_o_d_e 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 _m_o_d_e argument) causes all subsequent writes to the file
to be forced to the then current end-of-file, regardless of
intervening calls to fseek(3S). If two separate processes
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 _m_o_d_e argument), both input and output
may be performed on the associated stream. However, output
must not be directly followed by input without an
SunOS 5.7 Last change: 28 Jan 1998 1
Standard I/O Functions fopen(3S)
intervening call to fflush(3S) or to a file positioning
function ( fseek(3S), fsetpos(3S) or rewind( 3S)), and input
must not be directly followed by output without an interven-
ing 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 _m_o_d_e is _w, a, w+ or a+ and the file did not previously
exist, upon successful completion, fopen() function will
mark for update the st_atime, st_ctime and st_mtime fields
of the file and the st_ctime and st_mtime fields of the
parent directory.
If _m_o_d_e is _w or w+ and the file did previously exist, upon
successful completion, fopen() will mark for update the
st_ctime and st_mtime fields of the file. The fopen() func-
tion will allocate a file descriptor as open(2) does.
The largest value that can be represented correctly in an
object of type off_t 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.
ERRORS
The fopen() function will fail if:
EACCES Search permission is denied on a component of the
path prefix, or the file exists and the permis-
sions specified by _m_o_d_e are denied, or the file
does not exist and write permission is denied for
the parent directory of the file to be created.
EINTR A signal was caught during the execution of
fopen().
EISDIR The named file is a directory and _m_o_d_e requires
write access.
ELOOP Too many symbolic links were encountered in
resolving _p_a_t_h.
EMFILE There are OPEN_MAX file descriptors currently open
SunOS 5.7 Last change: 28 Jan 1998 2
Standard I/O Functions fopen(3S)
in the calling process.
ENAMETOOLONG
The length of the _f_i_l_e_n_a_m_e exceeds _P_A_T_H__M_A_X or a
pathname component is longer than _N_A_M_E__M_A_X.
ENFILE The maximum allowable number of files is currently
open in the system.
ENOENT A component of _f_i_l_e_n_a_m_e does not name an existing
file or _f_i_l_e_n_a_m_e is an empty string.
ENOSPC The directory or file system that would contain
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 associated with this
special file does not exist.
EOVERFLOW The current value of the file position cannot be
represented correctly in an object of type fpos_t.
EROFS The named file resides on a read-only file system
and _m_o_d_e requires write access.
The fopen() function may fail if:
EINVAL The value of the _m_o_d_e argument is not valid.
EMFILE The number of streams currently open in the cal-
ling process is either FOPEN_MAX or STREAM_MAX.
ENAMETOOLONG
Pathname resolution of a symbolic link produced an
intermediate result whose length exceeds _P_A_T_H__M_A_X.
ENOMEM Insufficient storage space is available.
ETXTBSY The file is a pure procedure (shared text) file
that is being executed and _m_o_d_e requires write
access.
USAGE
The number of streams that a process can have open at one
time is STREAM_MAX. If defined, it has the same value as
FOPEN_MAX.
The fopen() function has a transitional interface for 64-bit
file offsets. See lf64(5).
SunOS 5.7 Last change: 28 Jan 1998 3
Standard I/O Functions fopen(3S)
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|______________________________|______________________________|
| MT-Level | MT-Safe |
|______________________________|______________________________|
SEE ALSO
fclose(3S), fdopen(3S), fflush(3S), freopen(3S),
fsetpos(3S), rewind(3S), attributes(5), lf64(5), stan-
dards(5)
SunOS 5.7 Last change: 28 Jan 1998 4
Last modified: Fri Aug 20 09:05:06 BRT 2004