read(2P) INTERACTIVE UNIX System (POSIX) read(2P)
NAME
read - read from file
SYNOPSIS
int read (fildes, buf, nbyte)
int fildes;
char *buf;
unsigned nbyte;
DESCRIPTION
The read system call attempts to read nbyte bytes from the
file associated with fildes into the buffer pointed to by
buf.
fildes is an open file descriptor obtained from a creat(2),
open(2P), dup(2), fcntl(2), or pipe(2) system call.
If nbyte is zero, the read() function returns zero and has
no other results.
On devices capable of seeking, the read starts at a position
in the file given by the file pointer associated with
fildes. Upon return from read, the file pointer is incre-
mented 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.
Upon successful completion, read returns 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 communica-
tion line (see ioctl(2) and termio(7)), if the read was
interrupted by a signal, or if the number of bytes left in
the file is less than nbyte bytes. A value of 0 is returned
when an end-of-file has been reached.
If a read() is interrupted by a signal before it reads any
data, it returns -1 with errno set to [EINTR]. If a read()
is interrupted by a signal after it has successfully read
some data, it returns the number of bytes read.
No data transfer occurs past the current end-of-file. If the
starting position is at or after the end-of-file, zero is
returned, except for device special files, where -1 is
returned with errno set to [ENXIO].
The maximum value of nbytes is {UINT_MAX}, i.e., nbyte
values greater than {INT_MAX} are supported.
When attempting to read from an empty pipe (or FIFO):
1. If no process has the pipe open for writing, read()
Rev. 1.1 Page 1
read(2P) INTERACTIVE UNIX System (POSIX) read(2P)
returns zero to indicate the end-of-file.
2. If some process has the pipe open for writing and
O_NONBLOCK is set, read() returns -1 and sets errno
to [EAGAIN].
3. If a process has the pipe open for writing and
O_NONBLOCK is clear, read() blocks 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:
1. If O_NONBLOCK is set, read() returns -1 and sets errno to
[EAGIN].
2. If O_NONBLOCK is clear, read() blocks until some data
becomes available.
3. The use of the O_NONBLOCK flag has no effect if there is
some data available.
For any portion of a regular file (prior to the end-of-file)
that has not been written, read() returns bytes with value
zero.
Upon successful completion, the read() function marks the
st_atime field of the file for update.
A read from a STREAMS file (see intro(2)) 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 streamio(7)) and can be tested
with the I_GRDOPT ioctl. In byte-stream mode, read will
retrieve data from the stream until it has retrieved nbyte
bytes, or until there is no more data to be retrieved.
Byte-stream mode ignores message boundaries.
In STREAMS message-nondiscard mode, read retrieves data
until it has read nbyte bytes or until it reaches a message
boundary. If the read 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 or getmsg(2) 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
returns are discarded and are not available for a subsequent
read or getmsg.
When attempting to read from a regular file with mandatory
Rev. 1.1 Page 2
read(2P) INTERACTIVE UNIX System (POSIX) read(2P)
file/record locking set (see chmod(2P)) and there is a
blocking (i.e., owned by another process) write lock on the
segment of the file to be read:
1. If O_NDELAY is set, the read will return a -1 and
set errno to [EAGAIN].
2. If O_NDELAY is clear, the read will sleep until the
blocking record lock is removed.
When attempting to read from an empty pipe (or FIFO):
1. If O_NDELAY is set, the read will return a 0.
2. If O_NDELAY is clear, the read will block until data
is written to the file or the file is no longer open
for writing.
When attempting to read a file associated with a terminal
that has no data currently available:
1. If O_NDELAY is set, the read will return a 0.
2. If O_NDELAY is clear, the read will block until data
becomes available.
When attempting to read a file associated with a stream that
has no data currently available:
1. If O_NDELAY is set, the read will return a -1 and
set errno to [EAGAIN].
2. If O_NDELAY is clear, the read will block until data
becomes available.
When reading from a STREAMS file, handling of zero-byte mes-
sages 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. The read system
call 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. 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 from a STREAMS file can only process data messages.
It cannot process any type of protocol message and will fail
if a protocol message is encountered at the stream head.
The read system call will fail if one or more of the
Rev. 1.1 Page 3
read(2P) INTERACTIVE UNIX System (POSIX) read(2P)
following are true:
[EAGAIN] Mandatory file/record locking was set,
O_NDELAY was set, and there was a blocking
record lock.
[EAGAIN] Total amount of system memory available when
reading via raw I/O is temporarily insuffi-
cient.
[EAGAIN] No message waiting to be read on a stream and
O_NDELAY flag 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 situation to occur.
[EFAULT] buf points outside the allocated address
space.
[EINTR] A signal was caught during the read system
call.
[EIO] A physical I/0 error has occurred.
[EIO] The implementation supports job control, the
process is in a background process group and
it is attempting to read from its controlling
terminal, and either the process is ignoring
or blocking the SIGTTIN signal or the process
is orphaned. This error may also be gen-
erated for implementation-defined reasons.
[ENXIO] The device associated with the file-
descriptor is a block-special or character-
special file, and the value of the file-
pointer is out of range.
[EINVAL] Attempted to read from a stream linked to a
multiplexer.
[ENOLCK] The system record lock table was full, so the
read 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.
Rev. 1.1 Page 4
read(2P) INTERACTIVE UNIX System (POSIX) read(2P)
A read from a STREAMS file will also fail if an error mes-
sage 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 will continue to
operate normally until the stream head read queue is empty.
Thereafter, it will return 0.
SEE ALSO
creat(2), dup(2), fcntl(2), getmsg(2), intro(2), ioctl(2),
open(2P), pipe(2).
streamio(7), termio(7) in the INTERACTIVE UNIX System
User's/System Administrator's Reference Manual.
DIAGNOSTICS
Upon successful completion a non-negative integer is
returned indicating the number of bytes actually read. Oth-
erwise, a -1 is returned and errno is set to indicate the
error.
Rev. 1.1 Page 5