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 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 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 sigaction(3V)). If read() or readv() is interrupted by a signal after successfully 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 “message-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 transferred, 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 fcntl() 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 connected is “disconnected” when the connection is broken; a stream is “disconnected” when a hangup condition occurs (for instance, when carrier 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 determined 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 received 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 address 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 negative.

    The sum of the iov_len values in the iov array overflowed 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)