|
|
|
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;
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 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.
read() and readv() return the number of bytes actually read on success. On failure, they return -1 and set errno to indicate the error.
The pointer associated with
fd
was negative.
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.
In addition to the above, readv() may set errno to:
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.
|
|
|
Created by unroff & hp-tools. © somebody (See intro for details). All Rights Reserved. Last modified 11/5/97