VREAD(2V)               GENIX Programmer's Manual               VREAD(2V)



      NAME
           vread - read virtually

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

      DESCRIPTION
           N.B.: This call is likely to be replaced  by  more  general  virtual
           memory facilities in the near future.

           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 sys-
           tem, 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  compan-
           ion  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.

           On the NS16000, vread is equivalent to read.

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

      DIAGNOSTICS
           A 0 is returned at end-of-file.  If the read  was  otherwise  unsuc-
           cessful,  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.





      Printed 11/16/83                                                        1

      VREAD(2V)               GENIX Programmer's Manual               VREAD(2V)



      BUGS
           This call is peculiar to this version of UNIX.  It  will  be  super-
           seded  by  more general virtual memory facilities in future versions
           of the system.



















































      Printed 11/16/83                                                        2