term% cat index.txt FOPEN(2) System Calls Manual FOPEN(2)
NAME
fopen, freopen, fdopen, fileno, fclose, sopenr, sopenw, sclose, fflush,
setvbuf, setbuf, fgetpos, ftell, fsetpos, fseek, rewind, feof, ferror,
clearerr - standard buffered input/output package
SYNOPSIS
#include <u.h>
#include <stdio.h>
FILE *fopen(char *filename, char *mode)
FILE *freopen(char *filename, char *mode, FILE *f)
FILE *fdopen(int fd, char *mode)
int fileno(FILE *f)
FILE *sopenr(char *s)
FILE *sopenw(void)
char *sclose(FILE *f)
int fclose(FILE *f)
int fflush(FILE *f)
int setvbuf(FILE *f, char *buf, int type, long size)
void setbuf(FILE *f, char *buf)
int fgetpos(FILE *f, long *pos)
long ftell(FILE *f)
int fsetpos(FILE *f, long *pos)
int fseek(FILE *f, long offset, int whence)
void rewind(FILE *f)
int feof(FILE *f)
int ferror(FILE *f)
void clearerr(FILE *f)
DESCRIPTION
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 descrip‐
tive 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
stdout standard output file
stderr standard 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 hav‐
ing 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 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 auto‐
matically 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 er‐
rors 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 func‐
tions 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 posi‐
tion 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 suc‐
cess, nonzero otherwise. Fseek obtains a new position, measured in
characters from the beginning of the file, by adding offset to the po‐
sition 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 posi‐
tion indicator to the beginning of the file.
An integer constant EOF is returned upon end of file or error by inte‐
ger-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 er‐
ror state.
SOURCE
/sys/src/libstdio
SEE ALSO
fprintf(2), fscanf(2), fgetc(2)
open(2), read(2)
DIAGNOSTICS
The value EOF is returned uniformly to indicate that a FILE pointer has
not been initialized with fopen, input (output) has been attempted on
an output (input) stream, or a FILE pointer designates corrupt or oth‐
erwise unintelligible FILE data.
Some of these functions set errstr.
BUGS
Buffering of output can prevent output data from being seen until long
after it is computed - perhaps never, as when an abort occurs between
buffer filling and flushing.
Buffering of input can cause a process to consume more input than it
actually uses. This can cause trouble across exec(2).
Buffering may delay the receipt of a write error until a subsequent
stdio writing, seeking, or file-closing call.
ANSI says that a file can be fully buffered only if the file is not at‐
tached to an interactive device. In Plan 9 all are fully buffered ex‐
cept standard error.
Fdopen, fileno, sopenr, sopenw, and sclose are not ANSI Stdio func‐
tions.
Stdio offers no support for runes or UTF characters. Unless external
compatibility is necessary, use bio(2), which supports UTF and is
smaller, faster, and simpler than Stdio.
FOPEN(2)