|
The functions described in this and related pages (fgetc(2), fprintf(2),
fscanf(2), and tmpfile(2)) implement the ANSI C buffered I/O package
with extensions.
A file with associated buffering is called a stream and is declared
to be a pointer to a defined type FILE. Fopen(2) creates certain
descriptive data for a stream and returns a pointer to designate
the stream in all further transactions. There are three normally
open streams with constant pointers declared in the include
file and associated with the standard open files:
stdin standard input file
stdoutstandard output file
stderrstandard error file
A constant pointer NULL designates no stream at all.
Fopen opens the file named by filename and associates a stream
with it. Fopen returns a pointer to be used to identify the stream
in subsequent operations, or NULL if the open fails. Mode is a
character string having one of the following values:
"r" open for reading
"w" truncate to zero length or create for writing
"a" append; open or create for writing at end of file
"r+" open for update (reading and writing)
"w+" truncate to zero length or create for update
"a+" append; open or create for update at end of file
In addition, each of the above strings can have a b somewhere
after the first character, meaning `binary file', but this implementation
makes no distinction between binary and text files.
Fclose causes the stream pointed to by f to be flushed (see below)
and does a close (see open(2)) on the associated file. It frees
any automatically allocated buffer. Fclose is called automatically
on exits(2) for all open streams.
Freopen is like open except that it reuses stream pointer f. Freopen
first attempts to close any file associated with f; it ignores
any errors in that close.
Fdopen associates a stream with an open Plan 9 file descriptor.
Fileno returns the number of the Plan 9 file descriptor associated
with the stream.
Sopenr associates a read–only stream with a null–terminated string.
Sopenw opens a stream for writing. No file descriptor is associated
with the stream; instead, all output is written to the stream
buffer.
Sclose closes a stream opened with sopenr or sopenw. It returns
a pointer to the 0 terminated buffer associated with the stream.
By default, output to a stream is fully buffered: it is accumulated
in a buffer until the buffer is full, and then write (see read(2))
is used to write the buffer. An exception is standard error, which
is line buffered: output is accumulated in a buffer until a newline
is written. Input is also fully buffered by default; this means
that read(2) is used to fill a buffer as much as it can, and then
characters are taken from that buffer until it empties. Setvbuf
changes the buffering method for file f according to type: either
_IOFBF for fully buffered, _IOLBF for line buffered, or _IONBF
for unbuffered (each character causes a read or write). If buf
is
supplied, it is used as the buffer and size should be its size;
If buf is zero, a buffer of the given size is allocated (except
for the unbuffered case) using malloc(2).
Setbuf is an older method for changing buffering. If buf is supplied,
it changes to fully buffered with the given buffer, which should
be of size BUFSIZ (defined in stdio.h). If buf is zero, the buffering
method changes to unbuffered.
Fflush flushes the buffer of output stream f, delivering any unwritten
buffered data to the host file.
There is a file position indicator associated with each stream.
It starts out pointing at the first character (unless the file
is opened with append mode, in which case the indicator is always
ignored). The file position indicator is maintained by the reading
and writing functions described in fgetc(2).
Fgetpos stores the current value of the file position indicator
for stream f in the object pointed to by pos. It returns zero
on success, nonzero otherwise. Ftell returns the current value
of the file position indicator. The file position indicator is
to be used only as an argument to fseek.
Fsetpos sets the file position indicator for stream f to the value
of the object pointed to by pos, which shall be a value returned
by an earlier call to fgetpos on the same stream. It returns zero
on success, nonzero otherwise. Fseek obtains a new position, measured
in characters from the beginning of the file, by adding
offset to the position specified by whence: the beginning of the
file if whence is SEEK_SET; the current value of the file position
indicator for SEEK_CUR; and the end–of–file for SEEK_END. Rewind
sets the file position indicator to the beginning of the file.
An integer constant EOF is returned upon end of file or error
by integer–valued functions that deal with streams. Feof returns
non–zero if and only if f is at its end of file.
Ferror returns non–zero if and only if f is in the error state.
It can get into the error state if a system call failed on the
associated file or a memory allocation failed. Clearerr takes
a stream out of the error state.
|