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>
int readv(
int filedes,
struct iovec *iov,
int iovcount );
PARAMETERS
filedes Specifies a file descriptor identifying the file
to be 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.
iov Points to an array of iovec structures that iden-
tifies the buffers into which the data is to be
placed.
iovcount 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 the buffer parameter. The readv() func-
tion 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):
o If no process has the pipe open for writing, the read()
function returns 0 (zero) to indicate End-of-File.
o 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_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].
When attempting to read from a character special file that
supports nonblocking reads, such as a terminal, and no data
is currently available:
o If neither O_NONBLOCK nor O_NDELAY is set, the read()
function will block until data becomes available.
o If O_NDELAY is set, the read() function returns 0.
o If O_NONBLOCK is set, the read() functions return -1
and sets errno to [EAGAIN] if no data is available.
The use of the O_NONBLOCK 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):
o If O_NDELAY and O_NONBLOCK are clear, the read() func-
tion blocks the calling process until the lock is
released, or read() is terminated by a signal.
o 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 func-
tions 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() func-
tion 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).
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 iovcount 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 readv() function
always fills an area completely before proceeding to the
next.
The iovec structure is defined in the sys/uio.h header file
and contains the following members:
caddr_t iov_base;
int iov_len;
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. Otherwise, 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.
ERRORS
If the read() or readv() function fails, errno may be set to
one of the following values.
[EBADF] The filedes parameter is not a valid file descrip-
tor open for reading.
[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 not
between 1 and 1024, inclusive.
The requested operation attempted to read from a
stream linked to a multiplexer.
[EAGAIN] The O_NONBLOCK flag is set for the file descriptor
and the process would be delayed in the read
operation.
The O_NONBLOCK flag is set, and the pipe (or FIFO)
to be read from was empty.
Enforced record locking is enabled, O_NDELAY or
O_NONBLOCK is set, and there is a write lock owned
by another process.
The O_NONBLOCK flag is set and no data was avail-
able. COMBINE WITH (2) ABOVE?
[EFAULT] The buffer or part of the iov points to a loca-
tion 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.
[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.
[ENXIO] The device specified by the file descriptor param-
eter fildes is a block special character or a
character special file, and the file pointer value
is out of range.
[ENOLCK] The file has mandatory enforcement mode file lock-
ing set and LOCK_MAX regions are already locked in
the system.
[EDEADLK] Enforcement mode file locking is enabled, O_NDELAY
and O_NONBLOCK are clear, and a deadlock condition
is detected.
[EBADMSG] The message that is waiting to be read is not a
data message.
RELATED INFORMATION
Functions: fcntl(2), lockf(3), lseek(2), open(2), pipe(2),
poll(2), socket(2), socketpair(2), opendir(3)
Acknowledgement and Disclaimer