read(2)                                                   read(2)



     NAME
          read, readv - read from file

     SYNOPSIS
          cc = read(d, buf, nbytes)
          int cc, d;
          char *buf;
          int nbytes;

          #include <sys/types.h>
          #include <sys/uio.h>

          cc = readv(d, iov, iovcnt)
          int cc, d;
          struct iovec *iov;
          int iovcnt;

     DESCRIPTION
          fildes is a file descriptor obtained from a creat, open,
          dup, fcntl, pipe, or socket system call.

          read attempts to read nbytes bytes from the file associated
          with fildes into the buffer pointed to by buf.  readv
          performs the same action, but scatters the input data into
          the iovcnt buffers specified by the members of the iovec
          array: iov[0], iov[1], ..., iov[iovcnt-1].

          For readv, the iovec structure is defined as

               struct iovec {
                    caddr_t   iov_base;
                    int  iov_len;
               };

          Each iovec entry specifies the base address and length of an
          area in memory where data should be placed. readv will
          always fill an area completely before proceeding to the
          next.

          On devices capable of seeking, the read starts at a position
          in the file given by the file pointer associated with
          fildes.  Upon return from read, the file pointer is
          incremented by the number of bytes actually read.

          Devices that are incapable of seeking always read from the
          current position.  The value of a file pointer associated
          with such a file is undefined.

          Upon successful completion, read and readv return the number
          of bytes actually read and placed in the buffer; this number
          may be less than nbytes if the file is associated with a
          communication line (see ioctl(2),  socket(2N), and



     Page 1                                        (last mod. 1/14/87)

     read(2)                                                   read(2)



          termio(7)), or if the number of bytes left in the file is
          less than nbytes bytes.  A value of 0 is returned when an
          end-of-file has been reached.

          When attempting to read from an empty pipe (or FIFO):

               If ONDELAY is set, the read will return a 0.

               If ONDELAY is clear, the read will block until data is
               written to the file or the file is no longer open for
               writing.

          When attempting to read a file associated with a tty that
          has no data currently available:

               If ONDELAY is set, the read will return a 0.

               If ONDELAY is clear, the read will block until data
               becomes available.

          read and readv will fail if one or more of the following is
          true:

          [EBADF]     fildes is not a valid file descriptor open for
                      reading.

          [EFAULT]    buf points outside the allocated address space.

          [EINTR]     A signal was caught during the read system call.

          In addition, readv may return one of the following errors:

          [EINVAL]
               iovcnt was less than or equal to 0, or greater than 16.

          [EINVAL]
               One of the iovlen values in the iov array was
               negative.

          [EINVAL]
               The sum of the iovlen values in the iov array
               overflowed a 32-bit integer.

     RETURN VALUE
          Upon successful completion a non-negative integer is
          returned indicating the number of bytes actually read.
          Otherwise, a -1 is returned and errno is set to indicate the
          error.

     SEE ALSO
          creat(2), fcntl(2), ioctl(2), open(2), pipe(2), socket(2N),
          termio(7).



     Page 2                                        (last mod. 1/14/87)