VREAD(2)

NAME
vread - read virtually

SYNOPSIS
vread(fildes, buffer, nbytes)
char *buffer;

DESCRIPTION
A file descriptor is a word returned from a successful open, creat, dup or pipe call. Buffer is the location of nbytes contiguous bytes into which the input will be placed. It is not guaranteed that all nbytes will be read (see read (2)). In particular, if the returned value is 0, then end-of-file has been reached.

Unlike read (2), vread does not necessarily or immediately fetch the data requested from fildes, but merely insures that the data will be fetched from the file descriptor sometime before the first reference to the data, at the system's discretion. Thus vread allows the system, among other possibilities, to choose to read data on demand, with whatever granularity is allowed by the memory management hardware, or to just read it in immediately as with read. A companion vwrite (2) call may be used with vread to provide an efficient mechanism for updating large files. The behavior of vread if other processes are writing to fildes is not defined.

Both the address of buffer and the current offset in fildes (as told by tell (2)) must be aligned to a multiple of VALSIZ (defined in ``<valign.h>''). The library routine valloc (3) allocates properly aligned blocks from the free list.

Note for non-virtual systems: the vread system call can be simulated (exactly, if less efficiently) by read. If the unit on which a vread is done is not capable of supporting efficient demand initialization (e.g. a terminal or a pipe), then the system may choose to treat a call to vread as if it were a call to read at its discretion.

SEE ALSO
read(2), write(2), vwrite (2), valloc(3)

DIAGNOSTICS
A 0 is returned at end-of-file. If the read was otherwise unsuccessful, a -1 is returned. Physical I/O errors, non-aligned or bad buffer addresses, preposterous nbytes, file descriptor not that of an input file, and file offset not properly aligned can all generate errors.

BUGS
You can't close a file descriptor which you have vread from while there are still pages in the file which haven't been fetched by the system into your address space. In no case can a file descriptor which had such pages at the point of a vfork be closed during the vfork.

The system refuses to truncate a file to which any process has a pending vread.

There is no primitive inverting vread to release the binding vread sets up so that the file may be closed. This can be only be done, clumsily, by reading another (plain) file onto the buffer area, or pulling the break back with break(2) to completely release the pages.