read(2)

NAME

read, readv − read from file

SYNOPSIS

ssize_t read (fildes, buf, nbyte)
int fildes;
char ∗buf;
size_t nbyte;

SYNOPSIS (4.2BSD)

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

int readv (fildes, iov, iovcnt)
int fildes;
struct iovec ∗iov;
int iovcnt;

DESCRIPTION

Fildes is a file descriptor obtained from a creat, open, dup, fcntl, socket/bind, or pipe system call.

read attempts to read nbyte bytes from the file associated with fildes 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 iovec array: iov[0], iov[1], ... , iov[iovcnt-1].

The iovec structure is defined as

struct iovec {
caddr_t iov_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 devices capable of seeking, the read starts at a position in the file given by the file pointer associated with fildes. Upon return from read, the file pointer is incremented by the number of bytes actually read.

Devices that are incapable of seeking always read from the current position. The value of a file pointer associated with such a file is undefined.

Upon successful completion, read and readv return the number of bytes actually read and placed in the buffer; which may be less than the number of bytes requested if the file is associated with a communication line (see ioctl(2), termio(7) and termios(7)), or there is insufficient space left in the file. A value of 0 is returned when an 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(7)], and can be tested with the I_GRDOPT ioctl. In byte-stream mode, read and readv will retrieve data from the stream until nbyte bytes have been read, 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 nbyte bytes have been read, 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 replaced on the stream, and can be retrieved by the next read, readv or getmsg(2) call. Message-discard mode also retrieves data until it has retrieved nbyte bytes, or it reaches a message boundary. 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 an ordinary file with enforced record locking enabled, and all or part of the file segment to be read has a write-lock owned by another process (i.e., a blocking write-lock):

If O_NDELAY or O_NONBLOCK is set the function read will return −1 and errno will be set to EAGAIN .

If O_NDELAY and O_NONBLOCK are clear, the function read will sleep until all blocking write-locks are removed, or the function read is terminated by a signal.

When attempting to read from an empty pipe (or FIFO):

If O_NDELAY is set, the read will return a -1 with errno set to EWOULDBLOCK. If O_NONBLOCK is set, the read will return a -1 with errno set to EAGAIN.

If O_NDELAY and O_NONBLOCK are clear, the read will block until data is written to the file or the file is no longer open for writing.

When attempting to read a file associated with a tty that has no data currently available:

If O_NDELAY is set, the read will return a 0. If O_NONBLOCK is set, the read will return a -1 with errno set to EAGAIN.

If O_NDELAY and O_NONBLOCK are clear, the read will block until data becomes available.

When attempting to read a file associated with a stream that has no data currently available:

If O_NDELAY is set, the read will return a -1 and set errno to EAGAIN.

If O_NDELAY is clear, the read will block until data becomes available.

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 nbyte bytes have been read, or until there is no more data to read, or until a zero-byte message block is encountered. The read or readv then returns 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 stream head.

For regular disk files, if the O_DSYNC bit of the file status flags is set, all I/O operations on the file descriptor complete as defined by synchronized I/O data integrity completion. If the O_SYNC bit of the file status flags is set, all I/O operations on the file descriptor complete as defined by synchronized I/O file integrity completion (refer to the open(2) man page for the definitions of synchronized I/O data and file integrity completions).

When attempting to read a file that has been opened in direct mode (i.e. O_DIRECT is set) the buffer pointed to by buf or iov->iov_base must be longword aligned. Additionally nbyte or iov->iov_len must be a multiple of the longword length (4 bytes) and less than the maximum physical transfer size (see CX/UX Programmer’s Guide for details). Lastly, the file pointer associated with fildes should be aligned to a multiple of the disk block size (1 Kbyte) before the read request is issued.

For pipes, FIFOs or character special devices, if the read is interrupted by a signal, the number of bytes transferred before the signal will be returned. If no bytes were transferred, -1 will be returned and errno will be set to EINTR.

For sockets, if an error occurs, the contents of buf are undefined. If the read was interrupted by a signal, the socket will be left in the same state as it was before the call, and errno will be set to EINTR.

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

[EAGAIN] Enforced record locking was enabled (see chmod(2)), O_NDELAY or O_NONBLOCK was set, and there was a write-lock owned by another process.

[EAGAIN] The O_NONBLOCK flag is set for the file descriptor and the process would be delayed in the read operation because data is not available.

[EAGAIN] No message waiting to be read on a stream and O_NDELAY flag set.

[EBADF] Fildes is not a valid file descriptor open for reading.

[EBADMSG] Message waiting to be read on a stream is not a data message.

[EDEADLK] Enforced record locking was enabled, O_NDELAY and O_NONBLOCK were clear, and a deadlock condition was detected.

[EFAULT] Buf points outside the allocated address space.

[EFAULT] The file is opened for direct mode and the buffer is not aligned on a longword (4-byte) boundary or the byte count is not a longword multiple.

[EFAULT] The file is opened for direct mode and the file pointer associated with fildes is not aligned to a multiple of the disk block size (1 Kbyte).

[ENOLCK] Enforced record locking was enabled and {LOCK_MAX} regions are already locked in the system.

[EINTR] A signal was caught during the system call. For a FIFO, pipe or character special device, no data will have been transferred. For a socket, it will be left in the same state as it was before the call.

[EINVAL] Attempted to read from a stream linked to a multiplexor.

[EIO] The process is in a background process group and is attempting to read from its controlling terminal, and either the process is ignoring or blocking the SIGTTIN signal or the process group of the process is orphaned.

[ENXIO] The file is opened for direct mode and the byte count was greater than the maximum physical transfer size.

[EWOULDBLOCK]
The O_NDELAY flag is set and process would be delayed in the read operation.

In addition, readv may return one of the following errors:

[EFAULT] Part of iov points outside the allocated address space.

[EINVAL] Iovcnt was less than or equal to 0, or greater than 16.

[EINVAL] One or more 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.

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 and readv will continue to operate normally until the stream head read queue is empty. Thereafter, it will return 0.

RETURN VALUE

Upon successful completion a non-negative integer is returned indicating the number of bytes actually read. Otherwise, a −1 is returned and errno is set to indicate the error.

NOTE

The read function is defined in the 88open Binary and Object Compatibility Standards (BCS/OCS) for use in BCS/OCS compliant applications. Both functions are defined in the 88open BCS/OCS Networking Supplements (BCSNS/OCSNS) for use in BCS/OCS compliant networking applications. OCS/OCSNS-defined functions may be accessed by passing OCS options to cc(1) and ld(1).

Museum

Related Articles