read(2) read(2)
NAME
read, readv - read from file
SYNOPSIS
#include <sys/types.h>
#include <sys/uio.h>
#include <unistd.h>
ssizet read(int fildes, void *buf, sizet nbyte);
ssizet readv(int fildes, const 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(), or pipe() 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 actu-
ally 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.
If the value of nbyte is greater than SSIZEMAX, the result is unde-
fined.
Page 1 Reliant UNIX 5.44 Printed 11/98
read(2) read(2)
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() rou-
tine 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
calls of read() to read 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 read() or readv() 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
ISRDOPT ioctl() request [see streamio(7)], and can be tested with the
IGRDOPT ioctl() request. In byte-stream mode, read() and readv() usu-
ally retrieve data from the stream until they have retrieved nbyte
bytes, or until there is no more data to be retrieved. Message boun-
daries are generally ignored.
In the 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 reading 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(), the effect is as follows:
- If ONONBLOCK is set, read() returns -1 and sets errno to EAGAIN.
- If ONONBLOCK is clear, read() sleeps until the blocking record
lock is removed.
When attempting to read from an empty pipe or a FIFO file, the effect
is as follows:
- 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 ONONBLOCK is
set, read() returns -1 and sets errno to EAGAIN.
- If ONONBLOCK is 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, the effect is as follows:
Page 2 Reliant UNIX 5.44 Printed 11/98
read(2) read(2)
- If ONONBLOCK is set, read() returns -1 and sets errno to EAGAIN.
- If ONONBLOCK is clear, read() blocks until data becomes available.
When attempting to read a file associated with a stream that is not a
pipe or FIFO file, or terminal, and that has no data currently avail-
able, the effect is as follows:
- If ONONBLOCK is set, read() returns -1 and sets errno to EAGAIN.
- If ONONBLOCK is 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 encoun-
tered. 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 mes-
sage 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 con-
trol-data mode or control-discard mode with the ISRDOPT ioctl(). In
control-data mode, control messages are converted to data messages
which can be read by read(). In control-discard mode, control messages
are discarded by read(), but any data associated with the control mes-
sages is returned to the user.
For regular files, no data transfer will occur past the offset maximum
established in the open file description associated with fildes.
read() and readv() may do a "partial read or write" due to the offset
maximum. That is, the value returned may be less than nbyte if the
number of bytes remaining which may be transferred is less than nbyte.
ERRORS
The following error code descriptions are function-specific. You will
find a general description in introprm2(2) or in errno(5).
read() and readv() fail if one or more of the following apply:
EAGAIN Mandatory file/record locking was set, ONONBLOCK was set,
and there was a blocking record lock.
Page 3 Reliant UNIX 5.44 Printed 11/98
read(2) read(2)
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.
EAGAIN No message is waiting to be read on a stream and
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 mes-
sage.
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 received during the system call read() or
readv(), before any data was read.
EINVAL Attempted to read from a stream linked to a multiplexer.
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 ignor-
ing 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.
EISDIR The fildes argument refers to a directory and the imple-
mentation does not allow the directory to be read using
read() or readv(). The readdir() function should be used
instead.
EOVERFLOW The file is a regular file, nbyte is greater than 0, the
starting position is before the end-of-file and the start-
ing position is greater than or equal to the offset max-
imum established in the open file description associated
with fildes.
Page 4 Reliant UNIX 5.44 Printed 11/98
read(2) read(2)
In addition, readv() may return one of the following errors:
EFAULT iov points outside the process' 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.
RESULT
On success a non-negative integer is returned indicating the number of
bytes actually read. Otherwise, a -1 is returned, errno is set to
indicate the error, and the contents of the buffer pointed to by buf
are undefined.
Note: Change due to ISO POSIX-1 standard:
If read() is interrupted by a signal after data has been read, the
number of bytes actually read is displayed. If a signal interrupts
before any data is read, -1 is returned and errno is set.
SEE ALSO
creat(2), dup(2), fcntl(2), getmsg(2), ioctl(2), open(2), pipe(2),
unistd(4), lfs(5), types(5), uio(5), streamio(7), termio(7).
Page 5 Reliant UNIX 5.44 Printed 11/98