READ(2)                          System Calls                          READ(2)

NAME

       read, readv - read input

SYNOPSIS

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

       ssize_t read (int d, void *buf, size_t nbytes);

       ssize_t readv (int d, const struct iovec *iov, int iovcnt);

DESCRIPTION

       read  attempts to read nbytes of data from the object referenced by the
       descriptor d into the buffer pointed to by  buf.   readv  performs  the
       same action, but scatters the input data into the iovcnt buffers speci‐
       fied  by  the  members  of  the  iov  array:   iov[0],   iov[1],   ...,
       iov[iovcnt-1].

       For readv, the iovec structure is defined as:

       struct iovec {
            void *iov_base;
            size_t 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  objects  capable of seeking, the read starts at a position given by
       the pointer associated with d (see lseek(2)).  Upon return  from  read,
       the pointer is incremented by the number of bytes actually read.

       Objects  that  are  not capable of seeking always read from the current
       position.  The value of the pointer associated with such an  object  is
       undefined.

       Upon  successful  completion, read and readv return the number of bytes
       actually read and placed in the buffer.  The system guarantees to  read
       the  number  of  bytes  requested if the descriptor references a normal
       file that has that many bytes left before the end-of-file,  but  in  no
       other case.

       If the file was opened with the GNO-specific flag O_TRANS, then newline
       translation will occur; any carridge return character (0x0d) read  from
       descriptor d will be converted to a line feed (0x0a).

RETURN VALUES

       If  successful,  the  number  of  bytes actually read is returned. Upon
       reading end-of-file, zero is returned.  Otherwise, a -1 is returned and
       the global variable errno is set to indicate the error.

ERRORS

       read and readv will succeed unless:

              EBADF  D is not a valid file or socket descriptor open for read‐
                     ing.

              EFAULT Buf points outside the allocated address space.

              EIO    An I/O error occurred while reading from the file system.

              EINTR  A read from a slow device was interrupted before any data
                     arrived by the delivery of a signal.

              EINVAL The pointer associated with d was negative.

              EAGAIN The  file  was  marked  for non-blocking I/O, and no data
                     were ready to be read.

       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 iov_len values in the iov array was negative.

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

SEE ALSO

       dup(2), fcntl(2), open(2), pipe(2), select(2), socket(2), socketpair(2)

STANDARDS

       Read is expected to conform to IEEE Std 1003.1-1988 (POSIX).

HISTORY

       The  readv  function call appeared in 4.2BSD.  A read function call ap‐
       peared in Version 6 AT&T UNIX.



GNO                             23 January 1997                        READ(2)