[Main]

Read System Call

     #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)

     ssize_t
     pread(int d, void *buf, size_t nbytes, off_t offset)

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 specified by
     the members of the iov array: iov[0], iov[1], ..., iov[iovcnt-1].
     Pread() performs the same function, but reads from the specified position
     in the file without modifying the file pointer.

     For readv(), the iovec structure is defined as:

	   struct iovec {
		   char   *iov_base;  /* Base address. */
		   size_t iov_len;    /* Length. */
	   };

     Each iovec entry specifies the base address and length of an area in mem-
     ory where data should be placed.  Readv() will always fill an area com-
     pletely 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 po-
     sition.  The value of the pointer associated with such an object is unde-
     fined.

     Upon successful completion, read(), readv(), and pread() return the num-
     ber of bytes actually read and placed in the buffer.  The system guaran-
     tees 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.

IMPLEMENTATION NOTES

     In the non-threaded library read() is implemented as the read syscall.

     In the threaded library, the read syscall is assembled to
     _thread_sys_read() and read() is implemented as a function which locks d
     for read, then calls _thread_sys_read().  If the call to
     global variable errno is set to indicate the error.

ERRORS

     Read(), readv(), and pread() 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.

     [EFAULT]	   Part of the iov points outside the process's allocated ad-
		   dress space.

     The pread() call may also return the following errors:

     [EINVAL]	   The specified file offset is invalid.

     [ESPIPE]	   The file descriptor is associated with a pipe, socket, or
		   FIFO.

STANDARDS

     The read() function call is expected to conform to IEEE Std1003.1-1990
     (``POSIX''). The readv() and pread() functions are expected to conform to
     X/Open Portability Guide Issue 4.2 (``XPG4.2'').

HISTORY

     The pread() function call appeared in AT&T System V.4 UNIX.  The readv()
     function call appeared in 4.2BSD. A read() function call appeared in Ver-
     sion 6 AT&T UNIX.