READ(2) SysV READ(2)
NAME
read - read from file
SYNOPSIS
int read (fildes, buf, nbyte)
int fildes;
char *buf;
unsigned nbyte;
DESCRIPTION
fildes is a file descriptor obtained from a creat(2), open(2), dup(2),
fcntl(2), or pipe(2) system call.
read attempts to read nbyte bytes from the file associated with fildes
into the buffer pointed to by buf.
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 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.
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 communication line (see ioctl(2) and
termio(7)), 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.
A read 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 by
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 until 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 file/record
locking set (see chmod(2)), and there is a blocking (that is, owned by
another process) write lock on the segment of the file to be read:
⊕ If O_NDELAY is set, the read will return a -1 and set errno to EAGAIN.
⊕ 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):
⊕ If O_NDELAY is set, the read will return a 0.
⊕ 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 tty that has no data
currently available:
⊕ If O_NDELAY is set, the read will return a 0.
⊕ 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:
⊕ If O_NDELAY is set, the read will return a -1 and set errno to EAGAIN.
⊕ If O_NDELAY is clear, the read will block 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. 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.
ERRORS
read will fail if one or more of the 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 insufficient.
[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.
[EINVAL] Attempted to read from a Stream linked to a multiplexor.
[ENOLCK] The system record lock table was full, so the read could not
go to sleep until the blocking record lock was removed.
A read from a STREAMS file will also fail 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
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), ioctl(2), intro(2), open(2), pipe(2),
getmsg(2).
streamio(7), termio(7) in Managing SysV System Software.
DIAGNOSTICS
Upon successful completion, a non-negative integer is returned indicating
the number of bytes actually read. Otherwise, a -1 is returned and errno
is set as indicated under "Errors."
NOTES
Under other implementations, read fails if the following is true:
[ENOLINK] fildes is on a remote machine and the link to that machine is
no longer active.