 |
Index for Section 2 |
|
 |
Alphabetical listing for R |
|
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);
The following version of the readv() function does not conform to current
standards and is supported only for backward compatibility:
#include <sys/types.h>
#include <sys/uio.h>
ssize_t readv(
int filedes,
struct iovec *iov,
int iov_count);
STANDARDS
Interfaces documented on this reference page conform to industry standards
as follows:
read(): XPG4, XPG4-UNIX
readv(): XPG4-UNIX
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
filedes Identifies the file from which data is read.
buffer Points to the buffer to receive data read.
nbytes Specifies the number of bytes to read from the file associated
with the filedes parameter.
offset Specifies the desired start position inside the file associated
with the filedes parameter.
iov Points 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:
void *iov_base;
size_t iov_len;
[Digital] The backward-compatible version of the iovec structure
contains the following members:
caddr_t iov_base;
int iov_len;
iov_count 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.
[XPG4-UNIX] If filedes refers to a socket, read() is equivalent to recv()
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. 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.
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.
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 (or 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 had opened the pipe for writing.
· [Digital] 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].
· [Digital] 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 had opened the pipe for writing.
When attempting to read a file (other than a pipe or FIFO) 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.
· [Digital] If O_NDELAY is set, and the file is a serial device, the
function returns -1 and sets errno to [EAGAIN].
· [Digital] If O_NDELAY is set, and the file is a STREAMS device, the
function returns 0 and sets errno to 0.
· [Digital] If O_NDELAY is clear, the function will block until data
becomes available.
· [Digital] 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.
The use of the O_NONBLOCK flag has no effect if there is some data
available.
[Digital] The use of the O_NDELAY flag has no effect if there is some data
available.
[Digital] 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 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.
[DIGITAL] For AdvFS or UFS files that are mounted with the mount -o Flag
option noatimes, the 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.
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 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.
Upon successful completion, readv() marks for update the st_atime field of
the file.
Reading Data From STREAMS Files
[XPG4-UNIX] 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.
[XPG4-UNIX] 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 it reaches
a message boundary. However, unread data remaining in a message after the
read() or pread() returns are discarded, and are not available for a
subsequent read(), pread(), readv(), or getmsg() call.
[XPG4-UNIX] 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, or
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.
[XPG4-UNIX] 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.
[XPG4-UNIX] 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()
command. 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.
[XPG4-UNIX] In addition, read(), pread(), and readv() will fail if the
STREAM head had 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
[Digital] 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.
[Digital] When debugging a module that includes the readv() function and
for which _XOPEN_SOURCE_EXTENDED has been defined, use _Ereadv to refer to
the readv() call. See standards(5) for information on when the
_XOPEN_SOURCE_EXTENDED macro is defined.
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, when 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 which spans the end of a partition.
ERRORS
The read(), pread(), and readv() functions set errno to the specified
values for the following conditions.
[EAGAIN] The O_NONBLOCK flag is set on this file and the process would be
delayed in the read(), pread(), or readv() operation.
[Digital] No message is waiting to be read on a STREAM and the
O_NDELAY or O_NONBLOCK flag is set.
[Digital] 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.
[EBADMSG] [XPG4-UNIX] The file is a STREAM file that is set to control-
normal mode and the message waiting to be read includes a control
part.
[Digital] The message waiting to be read on a STREAM is not a
data message system call.
[Digital] The message that is waiting to be read is not a data
message.
[EDEADLK] [Digital] Enforcement mode file locking is enabled, O_NDELAY and
O_NONBLOCK are clear, and a deadlock condition is detected.
[EFAULT] [Digital] The buffer or part of the iov points to a location
outside of the allocated address space of the process.
[EINTR] A read on a pipe is interrupted by a signal and no bytes have
been transferred through the pipe.
[EINVAL] [XPG4-UNIX] The STREAM or multiplexer referenced by filedes is
linked (directly or indirectly) downstream from a multiplexer.
[XPG4-UNIX] The sum of the iov_len values in the iov array
overflowed an ssize_t.
[XPG4-UNIX] The value of the iovcount parameter was less than or
equal to 0, or greater than IOV_MAX.
[Digital] The file position pointer associated with the filedes
parameter was negative.
[Digital] The sum of the iov_len values in the iov array was
negative or overflowed a 32-bit integer.
[Digital] The requested operation attempted to read from a
STREAM linked to a multiplexer.
[EIO] [XPG4-UNIX] A physical I/O error has 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.
[ENOLCK] [Digital] The file has enforcement mode file locking set and
allocating another locked region would exceed the configurable
system limit of NLOCK_RECORD.
[ENOSPC] [Digital] An attempt was made to read past the "early warning"
EOT while this indicator was enabled.
[ENXIO] 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:
[ESPIPE] The file specified by filedes is associated with a pipe or FIFO.
For NFS file access, if the read() or pread() function fails, errno may
also be set to one of the following values:
[EBADRPC] [Digital] Indicates that the client has requested more data than
the server agreed to provide.
[EFBIG] [Digital] For filesystems mounted with the nfsv2 option, the
process attempted to read beyond the 2 gigabyte boundary.
[EISDIR] [Digital] 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] [Digital] Indicates either that the system file table is full, or
that there are too many files currently open in the system.
[ENOBUFS] [Digital] 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] [Digital] 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), getmsg(2), lockf(3),
lseek(2), mtio(7), open(2), pipe(2), poll(2), socket(2), socketpair(2),
termios(4), streamio(7), opendir(3) lockf(3)
Standards: standards(5)