home | help 
READ(2V)								READ(2V)

NAME
     read, readv - read input

SYNOPSIS
     int read(fd, buf, nbyte)
     int fd;
     char *buf;
     int nbyte;

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

     int readv(fd, iov, iovcnt)
     int fd;
     struct iovec *iov;
     int iovcnt;

DESCRIPTION
     read()  attempts  to read nbyte bytes of data from the object referenced by
     the descriptor fd into the buffer pointed to by buf.  readv() performs  the
     same  action as read(), but scatters the input data into the iovcnt buffers
     specified	by  the  members  of  the   iov   array:   iov[0],iov[1],   ...,
     iov[iovcnt-1].

     If  nbyte is zero, read() takes no action and returns 0.  readv(), however,
     returns -1 and sets the global variable errno (see ERRORS below).

     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 objects capable of seeking, the read() starts at a position given by the
     pointer  associated  with fd (see lseek(2V)).  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  posi-
     tion.   The  value  of  the pointer associated with such an object is unde-
     fined.

     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  which
     has  that	many  bytes  left  before the EOF (end of file), but in no other
     case.

     If the process calling read() or readv() receives a signal before any  data
     are  read,  the  system call is restarted unless the process explicitly set
     the signal to interrupt the call using sigvec()  or  sigaction()  (see  the
     discussions  of  SV_INTERRUPT  on	sigvec(2)  and	SA_INTERRUPT  on  sigac-
     tion(3V)).  If read() or readv() is interrupted by a signal after	success-
     fully reading some data, it returns the number of bytes read.

     If  nbyte	is not zero and read() returns 0, then EOF has been reached.  If
     readv() returns 0, then EOF has been reached.

     A read() or readv() from a STREAMS file (see intro(2)) can operate in three
     different modes: "byte-stream" mode, "message-nondiscard" mode,  and  "mes-
     sage-discard"  mode.  The default is byte-stream mode.  This can be changed
     using the I_SRDOPT ioctl(2) request (see streamio(4)), and  can  be  tested
     with the I_GRDOPT ioctl() request.  In byte-stream mode, read() and readv()
     will  retrieve  data  from the stream until as many bytes as were requested
     are transferred, or until there is no more data  to  be  retrieved.   Byte-
     stream mode ignores message boundaries.

     In  STREAMS  message-nondiscard mode, read() and readv() will retrieve data
     until as many bytes as were requested are transferred, or until  a  message
     boundary  is  reached.   If the read() or readv() does not retrieve all the
     data in a message, the remaining data are left on the stream,  and  can  be
     retrieved	by the next read(), readv(), or getmsg(2) call.  Message-discard
     mode also retrieves data until as many bytes as were requested  are  trans-
     ferred,  or  a message boundary is reached.  However, unread data remaining
     in a message after the read() or readv() returns are discarded, and are not
     available for a subsequent read(), readv(), or getmsg().

     When attempting to read from a descriptor associated with	an  empty  pipe,
     socket, FIFO, or stream:

     *	If  the  object  the descriptor is associated with is marked for 4.2BSD-
	style non-blocking I/O (with the FIONBIO ioctl() request or  a	call  to
	fcntl(2V)  using the FNDELAY flag from <sys/file.h> or the O_NDELAY flag
	from <fcntl.h> in the 4.2BSD environment), the read will return  -1  and
	errno will be set to EWOULDBLOCK.

     *	If  the  descriptor is marked for System V-style non-blocking I/O (using
	fcntl() with the FNBIO flag from <sys/file.h> or the O_NDELAY flag  from
	<fcntl.h>  in the System V environment), and does not refer to a stream,
	the read will return 0.  Note: this is indistinguishable from EOF.

     *	If the descriptor is marked for POSIX-style non-blocking I/O (using  fc-
	ntl()  with  the O_NONBLOCK flag from <fcntl.h>) and refers to a stream,
	the read will return -1 and errno will be set to EAGAIN.

     *	If neither the descriptor nor the object it refers  to	are  marked  for
	non-blocking I/O, the read will block until data is available to be read
	or the object has been "disconnected".	A pipe or FIFO is "disconnected"
	when  no process has the object open for writing; a socket that was con-
	nected is "disconnected" when the connection  is  broken;  a  stream  is
	"disconnected"	when  a hangup condition occurs (for instance, when car-
	rier drops on a terminal).

     If the descriptor or the object is marked for non-blocking  I/O,  and  less
     data  are	available  than are requested by the read() or readv(), only the
     data that are available are returned, and	the  count  indicates  how  many
     bytes of data were actually read.

     When  reading from a STREAMS file, handling of zero-byte messages is deter-
     mined by the current read mode setting.  In byte-stream  mode,  read()  and
     readv()  accept data until as many bytes as were requested are transferred,
     or until there is no more data to read, or until a zero-byte message  block
     is  encountered.	read() and readv() then return the number of bytes read,
     and places the zero-byte message back on the stream to be retrieved by  the
     next  read(),  readv(),  or  getmsg().  In the two other modes, a zero-byte
     message returns a value of 0 and the message is removed  from  the  stream.
     When  a zero-byte message is read as the first message on a stream, a value
     of 0 is returned regardless of the read mode.

     A read() or readv() from a STREAMS file can only process data messages.  It
     cannot process any type of protocol message and will  fail  if  a	protocol
     message is encountered at the streamhead.

     Upon successful completion, read() and readv() mark for update the st_atime
     field of the file.

RETURN VALUES
     read() and readv() return the number of bytes actually read on success.  On
     failure, they return -1 and set errno to indicate the error.

ERRORS
     EAGAIN		 The  descriptor  referred  to	a stream, was marked for
			 System V-style non-blocking I/O, and no data were ready
			 to be read.

     EBADF		 d is not a valid file descriptor open for reading.

     EBADMSG		 The message waiting to be read on a  stream  is  not  a
			 data message.

     EFAULT		 buf points outside the allocated address space.

     EINTR		 The  process  performing  a read from a slow device re-
			 ceived a signal before any data arrived, and the signal
			 was set to interrupt the system call.

     EINVAL		 The stream is linked below a multiplexor.

			 The pointer associated with fd was negative.

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

			 The  calling  process	is in a background process group
			 and is attempting to read from its controlling terminal
			 and the process is ignoring or blocking SIGTTIN.

			 The calling process is in a  background  process  group
			 and is attempting to read from its controlling terminal
			 and the process is orphaned.

     EISDIR		 fd  refers  to  a  directory  which is on a file system
			 mounted using the NFS.

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

     In addition to the above, readv() may set errno to:

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

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

			 One of the iov_len values in the iov  array  was  nega-
			 tive.

			 The  sum  of  the iov_len values in the iov array over-
			 flowed a 32-bit integer.

     A read() or readv() from a STREAMS file will also fail if an error  message
     is  received  at  the stream head.  In this case, errno is set to the value
     returned in the error message.  If a hangup  occurs  on  the  stream  being
     read,  read()  will continue to operate normally until the stream head read
     queue is empty.  Thereafter, it will return 0.

SEE ALSO
     dup(2V), fcntl(2V), getmsg(2),  intro(2),	ioctl(2),  lseek(2V),  open(2V),
     pipe(2V), select(2), socket(2), socketpair(2), streamio(4), termio(4)

				 21 January 1990			READ(2V)
home | help