READ(2-POSIX) RISC/os Reference Manual READ(2-POSIX)
NAME
read - read input
SYNOPSIS
ssizet read(fildes, buf, nbyte)
int fildes;
char *buf;
sizet nbyte;
DESCRIPTION
read attempts to read nbyte of data from the object refer-
enced by the descriptor fildes into the buffer pointed to by
buf.
On objects capable of seeking, the read starts at a position
given by the file offset associated with fildes (see
lseek(2)). Before successful return from read, the file
offset is incremented by the number of bytes actually read.
Objects that are not capable of seeking always read from the
current position. The file offset associated with such an
object is undefined.
If nbyte is zero, read returns zero immediately and has no
other effect. If the value of nbyte is greater than
{SSIZE_MAX} it is treated as an unsigned number.
Upon successful completion, read returns the number of bytes
actually read and placed in the buffer. This number is
never greater than nbyte. The value returned may be less
than nbyte if the number of bytes left in the file is less
than nbyte, if the read request was interrupted by a signal,
or if the file is a pipe or FIFO or special file and has
fewer than nbyte bytes immediately available for reading.
For example, a read from a file associated with a terminal
may return one typed line of data.
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 success-
fully read some data, it returns the number of bytes read.
No data transfer shall occur past the current end-of-file.
If the starting position is at or after the end-of-file,
zero is returned.
When attempting to read from an empty pipe or FIFO:
1. If no process has the pipe open for writing and
O_NONBLOCK is set, read returns zero to indicate end-of-
file.
Printed 1/15/91 Page 1
READ(2-POSIX) RISC/os Reference Manual READ(2-POSIX)
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 some process has the pipe open for writing and
O_NONBLOCK is clear, read blocks until some data is writ-
ten 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
EAGAIN.
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, read marks the st_atime field of
the file for update.
RETURN VALUE
If successful, the number of bytes actually read is
returned. Otherwise, a -1 is returned and the global vari-
able errno is set to indicate the error.
ERRORS
read will fail if one or more of the following are true:
[EBADF] fildes is not a valid file descriptor
open for reading.
[EFAULT] buf points outside the allocated address
space.
[EIO] An I/O error occurred while reading from
the file system, or the process is in a
background process group and is attempt-
ing to read from its controlling termi-
nal, and either the process is ignoring
or blocking the SIGTTIN signal or the
process group of the process is
orphaned.
Page 2 Printed 1/15/91
READ(2-POSIX) RISC/os Reference Manual READ(2-POSIX)
[EINTR] The read was interrupted by the delivery
of a signal before any data arrived.
[EAGAIN] The file was marked for non-blocking
I/O, and the process would be delayed in
the read operation.
SEE ALSO
creat(2), dup(2), fcntl(2), lseek(2), open(2), pipe(2).
Printed 1/15/91 Page 3