NAME

read, readv − Reads from a file. 

SYNOPSIS

#include <unistd.h>
ssize_t read(
int filedes,
void ∗buffer,
size_t nbytes ); #include <sys/types.h>
#include <sys/uio.h> ssize_t readv(
int filedes,
struct iovec ∗iov,
int iov_count );

PARAMETERS

filedesIdentifies the file from which data is 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 which identifies the buffers into which the data is to be placed.  The iovec structure is defined in the sys/uio.h header file and contains the following members:

caddr_t  iov_base;
int      iov_len;

iov_countSpecifies 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 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 0.

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

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 is set, the read() function returns -1 and sets errno to [EAGAIN] if no data is available.  The use of the O_NONBLOCK flag has no if there is some data available. 

       •If O_NDELAY is set and the file is a serial device, the read() function returns -1 and sets errno to [EAGAIN] if no data is available.  The use of the O_NDELAY flag has no effect if there is some data available. 

       •If O_NDELAY is set and the file is a STREAMS device, the read() function returns 0 and sets errno to 0 if no data is available.  The use of the O_NDELAY 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). If the file is a character special device that has been the target of a stopio() function, subsequent reads from the device will terminate with an [EBADF] error and the process delivers a SIGHUP signal.

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 iov_count 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 iovcount parameter is valid if greater than 0 (zero) and less than or equal to UIO_MAXIOV, which is defined in the sys/uio.h header file.  The readv() function always fills an area completely before proceeding to the next.

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. 

NOTES

AES Support Level:
Full use (read())

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 regular file that has the same number of bytes left before the End-of-File. If the read() and readv() functions fail, 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. 

End-of-Media Handling for Tapes

If reading goes beyond the "early warning" EOT indicator while this indicator is disabled, the read() and readv() functions will return the number of bytes actually read and placed into the buffer. The read() and readv() functions return a value of -1, if:

       •Attempting to read past the "real EOT". 

       •Attempting to read past "early warning" EOT indicator while this indicator is enabled. 

Refer to mtio(7) for information on enabling and disabling "early warning" EOT. 

End-of-Media Handling for Disks

Disk End-of-Media handling is POSIX-conformant.  Attempting to read at or beyond the end of a partition returns a value of 0.  A partial read returns the number of bytes actually read.  Note:  A partial read is a request which spans the end of a partition.

ERRORS

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

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

The O_NONBLOCK flag is set on this file and the process would be delayed in the read operation. 

An enforcement mode record lock is outstanding in the portion of the file that is to be read. 

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

The read() addresses a file descriptor that references a character device that has previously been the subject of a successful stopio() call.

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

The message that is waiting to be read is not a data message. 

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

[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.

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

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

The value of the iovcount parameter was less than or equal to 0, or greater than UIO_MAXIOV. 

The requested operation attempted to read from a Stream linked to a multiplexer. 

[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.  A physical I/O error has occurred. 

[ENOLCK]The file has enforcement mode file locking set and allocating another locked region would exceed the configurable system limit of NLOCK_RECORD. 

[ENOSPC]Attempted to read past the "early warning" EOT while this indicator was enabled. 

[ENXIO]The device specified by the file descriptor parameter fildes is a block special character or a character special file, and the file pointer value is out of range. 

For NFS file access, if the read() function fails, errno may also be set to one of the following values:

[EBADRPC]Indicates that the client has requested more data than the server agreed to provide. 

[EFBIG]For filesystems mounted with the nfsv2 option, the process attempted to read beyond the 2 gigabyte boundary. 

[EISDIR]Indicates either that the request was for a write access to a file but the specified filename was actually a directory, or that the function was trying to rename a directory as a file. 

[ENFILE]Indicates either that the system file table is full, or that there are too many files currently open in the system. 

[ENOBUFS]Indicates insufficient resources, such as buffers, to complete the call.  Typically, a call used with sockets has failed due to a shortage of message or send/receive buffer space. 

[ESTALE]Indicates a stale NFS file handle.  An opened file was deleted by the server or another client; a client cannot open a file because the server has unmounted or unexported the remote directory; or the directory that contains an opened file was either unmounted or unexported by the server. 

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 hang up 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), creat(2), dup(2), ioctl(2), getmsg(2), lockf(3), lseek(2), mtio(7), open(2), pipe(2), poll(2), socket(2), socketpair(2), termios(4), streamio(7), stopio(3), opendir(3) lockf(3),