OSF

NAME

read, readv −  Reads from a file

SYNOPSIS

int read(
int filedes,
char ∗buffer,
unsigned int nbytes ); #include <sys/types.h>
#include <sys/uio.h> int readv(
int filedes,
struct iovec ∗iov,
int iovcount );

PARAMETERS

filedesSpecifies a file descriptor identifying the object to be read. 

bufferPoints to the buffer to receive data read. 

nbytesSpecifies the number of bytes to read from the file associated with the filedes parameter. 

iovPoints to an array of iovec structures that identifies the buffers into which the data is to be placed. 

iovcountSpecifies the number of iovec structures pointed to by the iov parameter. 

DESCRIPTION

The read() function attempts to read nbytes of data from the file associated with the filedes parameter into the buffer pointed to by the the buffer parameter.  The readv() function performs the same action as the read() function, but scatters the input data into the buffers specified by the array of iovec structures pointed to by the iov parameter. 

On regular files and devices capable of seeking, the read() function starts at a position in the file given by the file pointer associated with the filedes parameter. Upon return from the read() function, 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. 

The read() and readv() functions, which suspend the calling process until the request is completed, are redefined so that only the calling thread is suspended. 

Upon successful completion, the read() function returns the number of bytes actually read and placed in the buffer.  This number will never be greater than nbytes.  The value returned may be less than nbytes if the number of bytes left in the file is less than nbytes, if the read() request was interrupted by a signal, or if the file is a pipe or FIFO or special file and has fewer than nbytes bytes immediately available for reading.  For example, a read() from a file associated with a terminal may return one typed line of data. 

No data transfer will occur past the current End-of-File.  If the starting position is at or after the End-of-File, 0 (zero) is returned. 

If the value of nbytes is 0 (zero), the read() function will return 0 and have no other results. 

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

       •If no process has the pipe open for writing, the read() function returns 0 (zero) to indicate End-of-File. 

       •If some process has the pipe open for writing:

       •If neither O_NONBLOCK nor O_NDELAY is set, the read() function will block until some data is written or the pipe is closed by all processes that had opened the pipe for writing. 

       •If O_NONBLOCK or O_NDELAY is set, the read() function returns a value of -1 and sets errno to [EAGAIN]. 

When attempting to read from a character special file that supports nonblocking reads, such as a terminal, and no data is currently available:

       •If neither O_NONBLOCK nor O_NDELAY is set, the read() function will block until data becomes available. 

       •If O_NONBLOCK or O_NDELAY is set, the read() functions return -1 and sets errno to [EAGAIN] if no data is available.  The use of the O_NONBLOCK flag has no effect if there is some data available. 

When attempting to read from a regular file with enforcement mode record locking enabled, and all or part of the region to be read is currently locked by another process (a write lock or exclusive lock):

       •If O_NDELAY and O_NONBLOCK are clear, the read() function blocks the calling process until the lock is released, or read() is terminated by a signal. 

       •If O_NDELAY or O_NONBLOCK  is set, the read() function returns -1 and sets errno to [EAGAIN]. 

If a read() function is interrupted by a signal before it reads any data, it will return −1 with errno set to [EINTR].  If a read() function is interrupted by a signal after it has successfully read some data, the behavior depends on how the handler for the arriving signal was installed. 

If the handler was installed with an indication that functions should not be restarted, the read() function returns a value of -1 and errno is set to [EINTR] (even if some data was already consumed).  If the handler was installed with an indication that functions should be restarted, and data had been read when the interrupt was handled, the read() function returns the amount of data consumed. 

A read() from a pipe or FIFO will never return with errno set to [EINTR] if it has transferred any data. 

For any portion of an ordinary file prior to the End-of-File that has not been written, the read() function returns bytes with value 0 (zero). 

Upon successful completion, the read() function marks the st_atime field of the file for update. 

The readv() function performs the same action as the read() function, but scatters the input data into the buffers specified by the array of iovec structures pointed to by the iov parameter.  The iovcount parameter specifies the number of buffers pointed to by the iov parameter.  Each iovec entry specifies the base address and length of an area in memory where data should be placed.  The readv() function always fills an area completely before proceeding to the next. 

The iovec structure is defined in the sys/uio.h header file and contains the following members:

caddr_t  iov_base;
int      iov_len;

NOTES

AES Support Level:
Full use (read())

A read() from a STREAMS 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()], and can be tested with the I_GRDOPT ioctl().  In byte-stream mode, read() retrieves data from the stream until it has retrieved nbyte bytes, or until there is no more data to be retrieved.  Byte-stream mode ignores message boundaries. 

In STREAMS message-nondiscard mode, read() retrieves data until it has read nbyte bytes, or until it reaches a message boundary.  If the read() 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() or getmsg() 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() returns are discarded, and are not available for a subsequent read() or getmsg(). 

When reading from a STREAMS file, handling of zero-byte messages is determined by the current read mode setting.  In byte-stream mode, read() accepts data until it has read nbyte bytes, or until there is no more data to read, or until a zero-byte message block is encountered.  read() then returns the number of bytes read, and places the zero-byte message back on the stream to be retrieved by the next read() 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() from a STREAMS file can only process data messages.  It cannot process any type of protocol message and fails if a protocol message is encountered at the stream head. 

RETURN VALUES

Upon successful completion, the read() and readv() functions return the number of bytes actually read and placed into buffers.  The system guarantees to read the number of bytes requested only if the descriptor references a normal file that has the same number of bytes left before the End-of-File.  Otherwise, a value of -1 is returned, errno is set to indicate the error, and the content of the buffer pointed to by the buffer parameter is indeterminate. 

ERRORS

If the read() or readv() function fails, errno may be set to one of the following values. 

[EBADF]The filedes parameter is not a valid file descriptor open for reading. 

[EINVAL]The file position pointer associated with the filedes parameter was negative. 

[EINVAL]The sum of the iov_len values in the iov array was negative or overflowed a 32-bit integer. 

[EINVAL]The value of the iovcount parameter was not between 1 and 16, inclusive. 

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

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

[EAGAIN]Enforced record locking is enabled, O_NDELAY or O_NONBLOCK is set, and there is a write lock owned by another process. 

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

[EFAULT]The buffer or part of  the iov points to a location outside of the allocated address space of the process. 

[EINTR]A read() was interrupted by a signal before any data arrived, and the signal handler was installed with an indication that functions are not to be restarted. 

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

[ENOLCK]The file has mandatory enforcement mode file locking set and LOCK_MAX regions are already locked in the system. 

[EDEADLK]Enforcement mode file locking is enabled, O_NDELAY and O_NONBLOCK are clear, and a deadlock condition is detected. 

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

A read from a STREAMS file also fails 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 continues to operate normally until the stream head read queue is empty.  Thereafter, it returns 0. 

RELATED INFORMATION

Functions: fcntl(2), lockf(3), lseek(2), open(2), pipe(2), poll(2), socket(2), socketpair(2), creat(2), dup(2), ioctl(2), open(2), pipe(2), getmsg(2), streamio(7), termio(4), opendir(3)