read(2) UNIX System V read(2)
NAME
read - read from file
SYNOPSIS
#include <sys/types.h>
#include <sys/uio.h>
#include <unistd.h>
int read(int fildes, void *buf, unsigned nbyte);
int readv(int fildes, struct iovec *iov, int iovcnt);
DESCRIPTION
read attempts to read nbyte bytes from the file associated with fildes
into the buffer pointed to by buf. If nbyte is zero, read returns zero
and has no other results. fildes is a file descriptor obtained from a
creat, open, dup, fcntl, pipe, or ioctl system call.
On devices capable of seeking, the read starts at a position in the file
given by the file pointer associated with fildes. On return from read,
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.
readv performs the same action as read, but places the input data into
the iovcnt buffers specified by the members of the iov array: iov[0],
iov[1], ..., iov[iovcnt-1].
For readv, the iovec structure contains the following members:
addrt iovbase;
sizet iovlen;
Each iovec entry specifies the base address and length of an area in
memory where data should be placed. readv always fills one buffer
completely before proceeding to the next.
On success, read and readv return the number of bytes actually read and
placed in the buffer; this number may be less than nbyte if the file is
associated with a communication line [see ioctl(2) and termio(7)], or if
the number of bytes left in the file is less than nbyte, or if the file
is a pipe or a special file. A value of 0 is returned when an end-of-
file has been reached.
read reads data previously written to a file. If any portion of an
ordinary file prior to the end of file has not been written, read 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
10/89 Page 1
read(2) UNIX System V read(2)
a value of 0 until data is written into the gap.
A read or readv from a STREAMS [see intro(2)] 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 ISRDOPT ioctl(2) request [see streamio(7)], and can be tested
with the IGRDOPT ioctl(2) request. In byte-stream mode, read and readv
usually retrieve data from the stream until they have retrieved nbyte
bytes, or until there
is no more data to be retrieved. Byte-stream mode usually ignores
message boundaries.
In STREAMS message-nondiscard mode, read and readv retrieve data until
they have read nbyte bytes, or until they reach a message boundary. If
read or readv does not retrieve all the data in a message, the remaining
data is replaced on the stream and can be retrieved by the next read or
readv 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 read or readv returns is discarded,
and is not available for a subsequent read, readv, or getmsg [see
getmsg(2)].
When attempting to read from a regular file with mandatory file/record
locking set [see chmod(2)], and there is a write lock owned by another
process on the segment of the file to be read:
If ONDELAY or ONONBLOCK is set, read returns -1 and sets errno to
EAGAIN.
If ONDELAY and ONONBLOCK are clear, read 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, read returns 0 to
indicate end-of-file.
If some process has the pipe open for writing and ONDELAY is set,
read returns 0.
If some process has the pipe open for writing and ONONBLOCK is
set, read returns -1 and sets errno to EAGAIN.
If ONDELAY and ONONBLOCK are clear, read 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:
Page 2 10/89
read(2) UNIX System V read(2)
If ONDELAY is set, read returns 0.
If ONONBLOCK is set, read returns -1 and sets errno to EAGAIN.
If ONDELAY and ONONBLOCK are clear, read blocks until data
becomes 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 ONDELAY or ONONBLOCK is set, read returns -1 and sets errno to
EAGAIN.
If ONDELAY and ONONBLOCK are clear, read 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, read
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. read
then returns the number of bytes read, and places the zero-byte message
back on the stream to be retrieved by the next read or getmsg [see
getmsg(2)]. 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 readv 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 read from a STREAMS file can only process messages with data
and without control information. The read 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 ISRDOPT ioctl(2). In control-data
mode, control messages are converted to data messages by read. In
control-discard mode, control messages are discarded by read, but any
data associated with the control messages is returned to the user.
read and readv fail if one or more of the following are true:
EAGAIN Mandatory file/record locking was set, ONDELAY or
ONONBLOCK was set, and there was a blocking record lock.
EAGAIN Total amount of system memory available when reading via
raw I/O is temporarily insufficient.
EAGAIN No data is waiting to be read on a file associated with a
tty device and ONONBLOCK was set.
10/89 Page 3
read(2) UNIX System V read(2)
EAGAIN No message is waiting to be read on a stream and ONDELAY
or ONONBLOCK was set.
EBADF fildes is not a valid file descriptor open for reading.
EBADMSG Message waiting to be read on a stream is not a data
message.
EDEADLK The read was going to go to sleep and cause a deadlock to
occur.
EFAULT buf points outside the allocated address space.
EINTR A signal was caught during the read or readv system call.
EINVAL Attempted to read from a stream linked to a multiplexor.
EIO 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.
ENOLCK The system record lock table was full, so the read or
readv could not go to sleep until the blocking record lock
was removed.
ENOLINK fildes is on a remote machine and the link to that machine
is no longer active.
ENXIO 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, readv may return one of the following errors:
EFAULT iov points outside the allocated address space.
EINVAL iovcnt was less than or equal to 0 or greater than 16.
EINVAL The sum of the iovlen values in the iov array overflowed
a 32-bit integer.
A read 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, read
continues to operate normally until the stream head read queue is empty.
Thereafter, it returns 0.
SEE ALSO
intro(2), creat(2), dup(2), fcntl(2), getmsg(2), ioctl(2), open(2),
pipe(2)
Page 4 10/89
read(2) UNIX System V read(2)
streamio(7), termio(7) in the System Administrator's Reference Manual
DIAGNOSTICS
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.
10/89 Page 5