read, pread, readv - read from a file
#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 );
Interfaces documented on this reference page conform to
industry standards 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.
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.
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 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 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
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 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_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 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_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 interrupted 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 noatimes 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 [Toc] [Back]
Function behavior discussed in this section is defined for
compilation environments that support XSH4.2 and higher
revisions of the XSH specification.
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 bytestream
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-discard
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).
[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.
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-offile.
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 [Toc] [Back]
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 [Toc] [Back]
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.
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 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 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 overflowed 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 provide. [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 directory that contains an opened file
was either unmounted or unexported by the server.
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)
[ Back ] |
