read(2)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 stan‐
dards as follows:
read(): XSH4.0, XSH4.2, XNS5.0
pread(): POSIX.1, XSH5.0
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 identi‐
fies the buffers into which the data is to be placed. The iovec struc‐
ture is defined in the <sys/uio.h> header file and contains the follow‐
ing 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 asso‐
ciated 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 param‐
eter) without changing the file pointer. The first three arguments to
pread() are the same as for 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 parame‐
ter 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 iov_count 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 associated
with such a file is undefined.
No data transfer will occur past the current end-of-file. If the start‐
ing 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 non‐
blocking 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_NONBLOCK
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 enforce‐
ment 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_NDELAY
and O_NONBLOCK are clear, the function blocks the calling process until
the lock is released, or the function is terminated by a signal. 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 -o noat‐
imes option of the mount command, 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 -o noatimes option.
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
Function behavior discussed in this section is defined for compilation
environments that support XSH4.2 and higher revisions of the XSH speci‐
fication.
A read() or pread() 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 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.
In STREAMS message-nondiscard mode, read() or pread() retrieves data
until it has read nbytes bytes or until it reaches a message 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.
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.
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.
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 encountered 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() request. In control-data mode read() or pread() converts any
control part to data and passes it to the application before passing
any data part originally present in the same message. In control-dis‐
card mode, read() or pread() discards message control parts but
returns, to the process, any data part in the message.
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() func‐
tion, 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], depend‐
ing 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 warn‐
ing” 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. Note that conditions marked
[XSH4.2] apply to compilation environments that support XSH4.2 and
higher versions of the XSH specification.
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 parame‐
ter is not a valid file descriptor open for reading.
[XSH4.2] The file is a STREAM file that is set to control-nor‐
mal 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 con‐
dition is detected. [Tru64 UNIX] The buffer or part of the iov
value 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 over‐
flowed an ssize_t buffer.
[XSH4.2] The value of the iov_count 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
blocking the SIGTTIN signal, or the process group is orphaned.
[Tru64 UNIX] The file has enforcement mode file locking set and
allocating 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 pro‐
vide. [Tru64 UNIX] For file systems mounted with the mount command's
-o nfsv2 option, the process attempted to read beyond the 2 gigabyte
boundary. For an NFS client,
fildes identifies a directory that resides on an NFS server. In this
case, the application must use readdir() or getdirentries() to read the
directory. [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 direc‐
tory that contains an opened file was either unmounted or unexported by
the server.
SEE ALSO
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)read(2)
