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.
Upon successful completion, read marks for update the st_atime field of
the file.
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.
If a read is interrupted by a signal after it has successfully read some
data, the call retruns the number of bytes read.
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 or O_NONBLOCK is set, the read will return a -1 and set
errno to EAGAIN.
+ If O_NDELAY or O_NONBLOCK are both 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 or O_NONBLOCK is set, the read will return a 0.
+ If O_NDELAY or O_NONBLOCK 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 or O_NONBLOCK is set, the read will return a 0.
+ If O_NDELAY or O_NONBLOCK 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 or O_NONBLOCK is set, the read will return a -1 and set
errno to EAGAIN.
+ If O_NDELAY and O_NONBLOCK 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 or O_NONBLOCK
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 or
O_NONBLOCK 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 Domain/OS System Administration Reference.
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
In prior releases, opening a sparse file (a file containing "holes" in it
that are not backed up by disk blocks) and reading through it from
beginning to end would cause disk blocks to be allocated for the sparse
regions of the file (that is, the file would cease to be sparse).
At SR10.4, if the file is accessed through ordinary open(2) and read
calls, is open for read, resides on an SR10.4 node and is NOT currently
being written by anyone, the sparseness of the file will be "mostly"
preserved. (For example, although file data blocks will not be
allocated, indirect filemap blocks will be.)
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.