read, pread, readv - read from file
#include <sys/types.h>
#include <sys/uio.h>
#include <unistd.h>
read( ) is Async-Signal-Safe attempts to read bytes from the file associated with into the buffer pointed to by If
nbyte is zero, returns zero and has no other results. is an open file descriptor. On devices capable of seeking,
the starts at a position in the file given by the file pointer associated with On return from 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. performs the same action as
except that it reads from a given position in the file without changing the file pointer. The first three arguments
to are the same as with the addition of a fourth argument offset for the desired position inside the file. An
attempt to perform a on a file that is incapable of seeking results in an error. performs the same action as but
places the input data into the iovcnt buffers specified by the members of the iov array: iov[0], iov[1],  . . .,
iov[iovcnt- 1]. The structure contains the following members:
caddr_t iov_base;
int iov_len;
Each iovec entry specifies the base address and length of an area in memory where data should be placed. always
fills one buffer completely before proceeding to the next. On success, and return the number of bytes actually
read and placed in the buffer; this number may be less than if the file is associated with a communication line
(see and or if the number of bytes left in the file is less than or if the file is a pipe or a special file. A value of
is returned when an end-of-file has been reached. reads data previously written to a file. If any portion of an
ordinary file prior to the end of file has not been written, returns the number of bytes read as 0. For example, the
lseek routine allows the file pointer to be set beyond the end of existing data in the file. If additional data is
written at this point, subsequent reads in the gap between the previous end of data and newly written data return
bytes with a value of 0 until data is written into the gap. A or from a STREAMS (see 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 request (see and can be tested with the request. In byte-stream
mode, and retrieve data from the stream until they have retrieved nbyte bytes, or until there is no more data to be
retrieved. Byte-stream mode ignores message boundaries. In STREAMS message-nondiscard mode, and retrieve
data until they have read nbyte bytes, or until they reach a message boundary. If or does not retrieve all the data
in a message, the remaining data is replaced on the stream and can be retrieved by the next or call. Message-
discard mode also retrieves data until it has retrieved nbyte bytes, or it reaches a message boundary. However,
unread data remaining in a message after the or returns is discarded, and is not available for a subsequent or (see
When attempting to read from a regular file with mandatory file/record locking set (see and there is a write lock
owned by another process on the segment of the file to be read: If O_NDELAY or O_NONBLOCK is set,
returns -1 and sets errno to EAGAIN. If O_NDELAY and O_NONBLOCK are clear, sleeps until the blocking
record lock is removed. When attempting to read from an empty pipe (or FIFO): If no process has the pipe open
for writing, returns to indicate end-of-file. If some process has the pipe open for writing and O_NDELAY is set,
returns If some process has the pipe open for writing and O_NONBLOCK is set, returns -1 and sets errno to
EAGAIN. If O_NDELAY and O_NONBLOCK are clear, blocks until data is written to the pipe or the pipe is
closed by all processes that had opened the pipe for writing. When attempting to read a file associated with a
terminal that has no data currently available: If O_NDELAY is set, returns If O_NONBLOCK is set, returns
-1 and sets errno to EAGAIN. If O_NDELAY and O_NONBLOCK are clear, blocks until data become
available. When attempting to read a file associated with a stream that is not a pipe or FIFO, or terminal, and
that has no data currently available: If O_NDELAY or O_NONBLOCK is set, returns -1 and sets errno to
EAGAIN. If O_NDELAY and O_NONBLOCK are clear, blocks until data becomes available. When reading
from a STREAMS file, handling of zero-byte messages is determined by the current read mode setting. In byte-
stream mode, accepts data until it has read nbyte bytes, or until there is no more data to read, or until a zero-byte
message block is encountered. then returns the number of bytes read, and places the zero-byte message back on
the stream to be retrieved by the next or (see In the two other modes, a zero-byte message returns a value of 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 is returned regardless of the mode. A or 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. Normally, a from a
STREAMS file can only process messages with data and without control information. The fails if a message
containing control information 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 In control-data mode, control messages
are converted to data messages by In control-discard mode, control messages are discarded by but any data
associated with the control messages is returned to the user. On success a non-negative integer is returned
indicating the number of bytes actually read. Otherwise, a -1 is returned and errno is set to indicate the error.
and fail if one or more of the following are true: Mandatory file/record locking was set, O_NDELAY or
O_NONBLOCK was set, and there was a blocking record lock. Total amount of system memory available
when reading using raw I/O is temporarily insufficient. No data is waiting to be read on a file associated with a
tty device and O_NONBLOCK was set. No message is waiting to be read on a stream and O_NDELAY or
O_NONBLOCK was set. is not a valid file descriptor open for reading. Message waiting to be read on a
stream is not a data message. The read was going to go to sleep and cause a deadlock to occur. points to an
illegal address.
A signal was caught during the read operation and no data was transferred. Attempted to read from a stream
linked to a multiplexor. A physical I/O error has occurred, or the process is in a background process group and
is attempting to read from its controlling terminal, and either the process is ignoring or blocking the SIGTTIN
signal or the process group of the process is orphaned.
refers to a directory on a file system type that does not support read operations on directories. The system record
lock table was full, so the or could not go to sleep until the blocking record lock was removed. fildes is on a
remote machine and the link to that machine is no longer active. The device associated with fildes is a block
special or character special file and the value of the file pointer is out of range. In addition, may return one of
the following errors: iov points outside the allocated address space. iovcnt was less than or equal to or greater
than or equal to {IOV_MAX}. (See for a definition of {IOV_MAX}). The sum of the iov_len values in the iov
array overflowed an int. In addition, fails and the file pointer remains unchanged if the following is true: is
associated with a pipe or fifo. A from a STREAMS file also fails if an error message is received at the stream
head. In this case, errno is set to the value returned in the error message. If a hangup occurs on the stream
being read, continues to operate normally until the stream head read queue is empty. Thereafter, it returns