READ(2-SVR3) RISC/os Reference Manual READ(2-SVR3)
NAME
read - read from file
SYNOPSIS
#include <bsd/sys/types.h>
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 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)], 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 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
Printed 11/19/92 Page 1
READ(2-SVR3) RISC/os Reference Manual READ(2-SVR3)
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 (i.e. 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 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. 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.
Page 2 Printed 11/19/92
READ(2-SVR3) RISC/os Reference Manual READ(2-SVR3)
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 read-
ing via raw IO 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 multi-
plexor.
[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.
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), ioctl(2), intro(2),
open(2), pipe(2).
streamio(7), termio(7) in the System Administrator's Refer-
ence Manual.
Printed 11/19/92 Page 3
READ(2-SVR3) RISC/os Reference Manual READ(2-SVR3)
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.
Page 4 Printed 11/19/92