READ(2V) — SYSTEM CALLS

NAME

read, readv − read input

SYNOPSIS

int read(d, buf, nbytes)
int d;
char ∗buf;
int nbytes;

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

int readv(d, iov, iovcnt)
int d;
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 specified by the members of the iov array: iov[0], iov[1], ..., iov[iovcnt−1].

For readv, the iovec structure is defined as

struct iovec {
caddr_tiov_base;
intiov_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 which has that many bytes left before the end-of-file, but in no other case.

If the returned value is 0, then end-of-file has been reached.

A read() or readv() from a STREAMS (see Intro(2)) file 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() request (see streamio(4)), and can be tested with the I_GRDOPT ioctl. 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 (2), or an fcntl() using the FNDELAY flag from <sys/file.h> or the O_NDELAY flag from <sys/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 (with an fcntl() using the FNBIO flag from <sys/file.h> or the O_NDELAY flag from <sys/fcntl.h> in the System V environment), and does not refer to a stream, the read will return 0. Note: this is indistinguishable from end-of-file.

If the descriptor is marked for System V-style non-blocking I/O, 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 is 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.

RETURN VALUE

If successful, the number of bytes actually read is returned. Otherwise, a −1 is returned and the global variable errno is set to indicate the error.

ERRORS

read() and readv() will fail if one or more of the following are true:

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

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

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

EFAULT buf points outside the allocated address space.

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

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

EINVAL The stream is linked below a multiplexor.

EINVAL The pointer associated with d was negative.

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

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.

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 iov points outside the process’s allocated address space.

A read() or readv() from a STREAMS file will also fail if an error message is received at the streamhead. 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.

Museum