read(2) System Calls Manual read(2)
NAME
read, pread, readv - Read from a file.
SYNOPSIS
#include <unistd.h>
ssize_t read(
int filedes,
void *buffer,
size_t nbytes);
ssize_t pread(
int filedes,
void *buffer,
size_t nbytes);
off_t offset);
#include <sys/uio.h>
ssize_t readv(
int filedes,
const struct iovec *iov,
int iov_count);
STANDARDS
Interfaces documented on this reference page conform to industry standards as follows:
read(): XSH4.2, XNS5.0
pread(): POSIX.1c
readv(): XSH4.2, XNS5.0
Refer to the standards(5) reference page for more information about industry standards and associated tags.
PARAMETERS
Identifies the file from which data is read. Points to the buffer to receive data that is being read. Specifies the number of bytes to
read from the file associated with the filedes parameter. Specifies the desired start position inside the file associated with the filedes
parameter. Points to an array of iovec structures that 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:
void *iov_base; size_t iov_len; Specifies 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.
If the value of nbytes is 0 (zero), the read() function returns 0 and has no other results.
[XNS5.0] If filedes refers to a socket, a read() request is equivalent to a recv() request with no flags set.
The pread() function performs the same action as read(), except that it reads from a given position in the file (specified by the offset
parameter) without changing the file pointer. The first three arguments to pread are the same as a read, the fourth argument to pread,
offset, specifies the desired position inside the file. An attempt to perform a pread() on a file that is incapable of seeking results in
an error.
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 parame-
ter. 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 IOV_MAX, which is defined in the sys/limits.h header file. The readv() function
always fills an area completely before proceeding to the next.
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 (for example, terminals) always read from the current position. The value of a file pointer associ-
ated with such a file is undefined.
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.
When attempting to read from an empty pipe (FIFO) the read() and pread() functions behave as follows: If no process has the pipe open for
writing, the function returns 0 (zero) to indicate end-of-file. If some process has the pipe open for writing and O_NONBLOCK is set, the
function returns a value of -1 and sets errno to [EAGAIN]. If some process has the pipe open for writing and O_NONBLOCK is clear, the
function will block until some data is written or the pipe is closed by all processes that opened the pipe for writing. [Tru64 UNIX] If
some process has the pipe open for writing and O_NDELAY is set, the function returns a value of -1 and sets errno to [EAGAIN]. [Tru64
UNIX] If some process has the pipe open for writing and O_NDELAY is clear, the function will block until some data is written or the pipe
is closed by all processes that opened the pipe for writing.
When attempting to read a file (other than a pipe) that supports nonblocking reads and has no data currently available, the read() and
pread() functions behave as follows: If O_NONBLOCK is set, the function returns -1 and sets errno to [EAGAIN]. If O_NONBLOCK is clear, the
function will block until data becomes available. [Tru64 UNIX] If O_NDELAY is set and the file is a serial device, the function returns
-1 and sets errno to [EAGAIN]. [Tru64 UNIX] If O_NDELAY is set and the file is a STREAMS device, the function returns 0 and sets errno to
0. [Tru64 UNIX] If O_NDELAY is clear, the function will block until data becomes available. [Tru64 UNIX] If both O_NDELAY and O_NON-
BLOCK are set and the file is a STREAMS device, the function returns -1 and sets errno to [EAGAIN]. The behavior of O_NONBLOCK takes
precedence over the behavior of O_NDELAY.
[Tru64 UNIX] The use of the O_NONBLOCK flag has no effect if there is some data available.
[Tru64 UNIX] 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), the read() and pread() functions behave as follows: If O_NDE-
LAY and O_NONBLOCK are clear, the function blocks the calling process until the lock is released, or the function is terminated by a sig-
nal. If O_NDELAY or O_NONBLOCK is set, the function returns -1 and sets errno to [EAGAIN].
The read() and pread() functions read data previously written to a file. If any portion of a regular file prior to the end-of-file has not
been written, the function returns bytes with value 0 (zero).
Upon successful completion, where nbytes is greater than 0 (zero), the read() or pread() function marks the st_atime field of the file for
update and 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() or pread() request was inter-
rupted by a signal, or if the file is a pipe (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.
[Tru64 UNIX] For AdvFS or UFS files that are mounted with the mount -o flag option noatimes, file access time changes are made in memory,
but are not flushed to disk until other file modifications occur. This behavior can improve server response time by decreasing the number
of disk I/O operations. However, the behavior violates POSIX standards and jeopardizes the integrity of file access times. See mount(8)
for more information about the mount -o flag option noatimes.
If a read() or pread() function is interrupted by a signal before it reads any data, it returns -1 with errno set to [EINTR].
If a read() or pread() function is interrupted by a signal after it has successfully read some data, it returns the number of bytes read.
Upon successful completion, readv() marks for update the st_atime field of the file.
Reading Data From STREAMS Files
[XSH4.2] A read() or pread() from a STREAMS file can operate in three different modes: byte-stream mode, message-nondiscard mode, and mes-
sage-discard mode. The default is byte-stream mode. This can be changed using the I_SRDOPT ioctl() request (see the streamio(7) reference
page) and can be tested with the I_GRDOPT ioctl(). In byte-stream mode, read() or pread() retrieves data from the STREAM until it has
retrieved nbytes bytes or until there is no more data to be retrieved. Byte-stream mode ignores message boundaries.
[XSH4.2] In STREAMS message-nondiscard mode, read() or pread() retrieves data until it has read nbytes bytes or until it reaches a mes-
sage boundary. If the read() or pread() 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(), pread(), or getmsg() call. Message-discard mode also retrieves data until it has retrieved nbytes bytes
or until it reaches a message boundary. However, unread data remaining in a message after the read() or pread() returns is discarded and
is not available for a subsequent read(), pread(), readv(), or getmsg() call.
[XSH4.2] When reading from a STREAMS file, handling of zero-byte messages is determined by the current read mode setting. In byte-stream
mode, read() or pread() accepts data until it has read nbytes bytes, until there is no more data to read, or until a zero-byte message
block is encountered. The read() or pread() function then returns the number of bytes read and places the zero-byte message back on the
STREAM to be retrieved by the next read(), pread(), or getmsg() call. 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.
[XSH4.2] A read() or pread() from a STREAMS file returns the data in the message at the front of the STREAM head read queue, regardless of
the priority band of the message.
[XSH4.2] By default, STREAMS are in control-normal mode, in which a read() or pread() from a STREAMS file can only process data messages
that contain a data part but do not contain a control part. The read() or pread() fails if a message containing a control part is encoun-
tered at the STREAM head. This default action can be changed by placing the STREAM in either control-data mode or control-discard mode
with the I_SRDOPT ioctl() command. In control-data mode read() or pread() converts any control part to data and passes it to the applica-
tion before passing any data part originally present in the same message. In control-discard mode, read() or pread() discards message con-
trol parts but returns, to the process, any data part in the message.
[XSH4.2] In addition, read(), pread(), and readv() will fail if the STREAM head processed an asynchronous error before the call. In this
case, the value of errno does not reflect the result of read(), pread(), and readv(), but reflects the prior error. If a hangup occurs on
the STREAM being read, read() or pread() continues to operate normally until the STREAM head read queue is empty. Thereafter, it returns 0
(zero).
NOTES
[Tru64 UNIX] For compatibility with earlier releases, values for iov_len that are greater than or equal to 2^63 will be treated as zero.
[Tru64 UNIX] The read(), pread(), and readv() functions, which suspend the calling process until the request is completed, are redefined
so that only the calling thread is suspended.
[Tru64 UNIX] When debugging a module that includes the readv() function, use _Ereadv to refer to the readv() call.
When a read(), pread(), write(), or pwrite() system call on a pipe is interrupted by a signal and no bytes have been transferred through
the pipe, a value of -1 is returned and errno is set to [EINTR]. This behavior is different from previous releases in which both read()
and write() either restarted the transfer or set errno to [EINTR], depending on the setting of the SA_RESTART flag for the interrupting
signal.
As a result of this change, applications must now either handle the [EINTR] return or block any expected signals for the duration of the
read(), pread(), write(), or pwrite() operation.
RETURN VALUES
Upon successful completion, the read(), pread(), 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(), pread(), 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(), pread(), and readv() functions will
return the number of bytes actually read and placed into the buffer. The read(), pread(), 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 that spans the end of a partition.
ERRORS
The read(), pread(), and readv() functions set errno to the specified values for the following conditions:
The O_NONBLOCK flag is set on this file and the process would be delayed in the read(), pread(), or readv() operation.
[Tru64 UNIX] No message is waiting to be read on a STREAM and the O_NDELAY or O_NONBLOCK flag is set.
[Tru64 UNIX] An enforcement mode record lock is outstanding in the portion of the file that is to be read. The filedes parameter
is not a valid file descriptor open for reading. [XSH4.2] The file is a STREAM file that is set to control-normal mode and the
message waiting to be read includes a control part.
[Tru64 UNIX] The message waiting to be read on a STREAM is not a data message system call.
[Tru64 UNIX] The message that is waiting to be read is not a data message. [Tru64 UNIX] Enforcement mode file locking is enabled,
O_NDELAY and O_NONBLOCK are clear, and a deadlock condition is detected. [Tru64 UNIX] The buffer or part of the iov points to a
location outside the allocated address space of the process. A read on a pipe (FIFO) is interrupted by a signal and no bytes have
been transferred through the pipe. [XSH4.2] The STREAM or multiplexer referenced by filedes is linked (directly or indirectly)
downstream from a multiplexer.
[XSH4.2] The sum of the iov_len values in the iov array overflowed an ssize_t.
[XSH4.2] The value of the iovcount parameter was less than or equal to 0, or greater than IOV_MAX.
[Tru64 UNIX] The file position pointer associated with the filedes parameter was negative.
[Tru64 UNIX] The sum of the iov_len values in the iov array was negative or overflowed a 32-bit integer.
[Tru64 UNIX] The requested operation attempted to read from a STREAM linked to a multiplexer. [XSH4.2] A physical I/O error
occurred.
The process is a member of a background process attempting to read from its controlling terminal, the process is ignoring or block-
ing the SIGTTIN signal, or the process group is orphaned. [Tru64 UNIX] The file has enforcement mode file locking set and allocat-
ing another locked region would exceed the configurable system limit of NLOCK_RECORD. [Tru64 UNIX] An attempt was made to read
past the "early warning" EOT while this indicator was enabled. The device specified by the file descriptor parameter filedes is a
block special character or a character special file, and the file pointer value is out of range.
In addition, the pread() function fails and the file pointer remains unchanged if the following is true: The file specified by filedes is
associated with a pipe (FIFO).
For NFS file access, if the read() or pread() function fails, errno may also be set to one of the following values: [Tru64 UNIX] Indicates
that the client has requested more data than the server agreed to provide. [Tru64 UNIX] For filesystems mounted with the nfsv2 option,
the process attempted to read beyond the 2 gigabyte boundary. [Tru64 UNIX] Indicates either that the request for write access to a file
specified a directory name instead of a filename, or that the function was trying to rename a directory as a file. [Tru64 UNIX] Indicates
either that the system file table is full or that too many files are currently open in the system. [Tru64 UNIX] 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. [Tru64 UNIX] 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.
RELATED INFORMATION
Functions: fcntl(2), creat(2), dup(2), ioctl(2), mtio(7), open(2), pipe(2), poll(2), socket(2), socketpair(2), termios(4), streamio(7),
opendir(3) lockf(3)
Standards: standards(5) delim off
read(2)