FIO(3) FIO(3)
NAME
Finit, Frdline, Fgetc, Fread, Fseek, Fundo, Fputc, Fprint,
Fwrite, Fflush, Ftie, Fclose, Fexit - fast buffered
input/output
SYNOPSIS
#include <fio.h> void Fundo(fd)
void Finit(fd, buf) long Fseek(fd, offset, ptr)
char *buf; long offset;
int Fclose(fd); int Fputc(fd, c)
int Fprint(fildes, format [, argl.o.n.g])Fread(fd, addr, nbytes)
int fildes; char *addr;
char *format; long nbytes;
char *Frdline(fd) long Fwrite(fd, addr, nbytes)
char *addr;
int FIOLINELEN(fd) long nbytes;
long FIOSEEK(fd) int Fflush(fd)
int Fgetc(fd) void Ftie(ifd, ofd)
Fexit(type)
DESCRIPTION
These routines provide buffered I/O, faster than, and incom-
patible with stdio(3). The routines can be called in any
order. I/O on different file descriptors is independent.
Finit initializes a buffer (whose type is Fbuffer) associ-
ated with the file descriptor fd. Any buffered input associ-
ated with fd will be lost. The buffer can be supplied by
the user (it should be at least sizeof(Fbuffer) bytes) or if
buf is (char *)0, Finit will use malloc(3). Finit must be
called after a stretch of non-fio activity, such as close or
lseek(2), between fio calls on the same file descriptor num-
ber; it is unnecessary, but harmless, before the first fio
activity on a given file descriptor number.
Fclose flushes the buffer for fd, frees the buffer if it was
allocated by Finit, and then closes fd.
Frdline reads a line from the file associated with the file
descriptor fd. The newline at the end of the line is
replaced by a 0 byte. Frdline returns a pointer to the
start of the line or `(char *)0' on end of file or read
error. The macro FIOLINELEN returns the length (not
FIO(3) FIO(3)
including the 0 byte) of the most recent line returned by
Frdline. The value is undefined after a call to any other
fio routine.
Fgetc returns the next character from the file descriptor
fd, or a negative value at end of file.
Fread reads nbytes of data from the file descriptor fd into
memory starting at addr. The number of bytes read is
returned on success and a negative value is returned if a
read error occurred.
Fseek applies lseek(2) to fd taking buffering into account.
It returns the new file offset. The macro FIOSEEK returns
the file offset of the next character to be processed.
Fundo makes the characters returned by the last call to
Frdline or Fgetc available for reading again. There is only
one level of undo.
Fputc outputs the low order 8 bits of c on the file associ-
ated with file descriptor fd. If this causes a write (see
read(2)) to occur and there is an error, a negative value is
returned. Otherwise, zero is returned.
Fprint is a buffered interface to print(3). If this causes a
write to occur and there is an error, a negative value is
returned. Otherwise, the number of chars output is
returned.
Fwrite outputs nbytes bytes of data starting at addr to the
file associated with file descriptor fd. If this causes a
write to occur and there is an error, a negative value is
returned. Otherwise, the number of bytes written is
returned.
Fflush causes any buffered output associated with fd to be
written; it must precede a call of close on fd. The return
is as for Fputc.
Ftie links together two file descriptors such that any fio-
initiated read(2) on ifd causes a Fflush of ofd (if it has
been initialized). It is appropriate for most programs used
as filters to do Ftie(0,1). The tie may be broken by
Ftie(ifd, -1).
Fexit is used to clean up all fio buffers. If type is zero,
the buffers are Fflushed, otherwise they are Fclosed.
Fexit(0) is automatically called at exit(3).
SEE ALSO
open(2), print(3), stdio(3)
FIO(3) FIO(3)
DIAGNOSTICS
Fio routines that return integers yield -1 if fd is not the
descriptor of an open file or if the operation is inapplica-
ble to fd.
BUGS
Frdline deletes characters from lines longer than 4095 char-
acters, ignores characters after the last newline in a file,
and will read past and end-of-file indication on a stream.
The data returned by Frdline may be overwritten by calls to
any other fio routine.
Fgetc is much slower than access through a pointer returned
by Frdline.
There is no scanf(3) analogue.