read(2) read(2)
NAME
read, readv - read from file
SYNOPSIS
ssizet read (fildes, buf, nbyte)
int fildes;
char *buf;
sizet nbyte;
SYNOPSIS (4.2BSD)
#include <sys/types.h>
#include <sys/uio.h>
int readv (fildes, iov, iovcnt)
int fildes;
struct iovec *iov;
int iovcnt;
DESCRIPTION
Fildes is a file descriptor obtained from a creat, open,
dup, fcntl, socket/bind, or pipe system call.
read attempts to read nbyte bytes from the file associated
with fildes into the buffer pointed to by buf. Readv per-
forms the same action, but scatters the input data into the
iovcnt buffers specified by the members of the iovec array:
iov[0], iov[1], ... , iov[iovcnt-1].
The iovec structure is defined as
struct iovec {
caddrt iovbase;
int iovlen;
};
Each iovec entry specifies the base address and length of an
area in memory where data should be placed. Readv will
always fill an area completely before proceeding to the
next.
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 and readv return the number
of bytes actually read and placed in the buffer; which may
be less than the number of bytes requested if the file is
Page 1 CX/UX Programmer's Reference Manual
read(2) read(2)
associated with a communication line (see ioctl(2), ter-
mio(7) and termios(7)), or there is insufficient space left
in the file. A value of 0 is returned when an end-of-file
has been reached.
A read or readv 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 and
readv will retrieve data from the stream until nbyte bytes
have been read, or until there is no more data to be
retrieved. Byte-stream mode ignores message boundaries.
In STREAMS message-nondiscard mode, read and readv will
retrieve data until nbyte bytes have been read, or until a
message boundary is reached. If the read or readv 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, readv 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 or readv returns are discarded,
and are not available for a subsequent read, readv or
getmsg.
When attempting to read from an ordinary file with enforced
record locking enabled, and all or part of the file segment
to be read has a write-lock owned by another process (i.e.,
a blocking write-lock):
If O_NDELAY or O_NONBLOCK is set the function read will
return -1 and errno will be set to EAGAIN .
If O_NDELAY and O_NONBLOCK are clear, the function read
will sleep until all blocking write-locks are removed,
or the function read is terminated by a signal.
When attempting to read from an empty pipe (or FIFO):
If O_NDELAY is set, the read will return a -1 with
errno set to EWOULDBLOCK. If O_NONBLOCK is set, the
read will return a -1 with errno set to EAGAIN.
If O_NDELAY and O_NONBLOCK are 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:
Page 2 CX/UX Programmer's Reference Manual
read(2) read(2)
If O_NDELAY is set, the read will return a 0. If
O_NONBLOCK is set, the read will return a -1 with errno
set to EAGAIN.
If O_NDELAY and O_NONBLOCK are 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 and readv accept data until nbyte
bytes have been read, or until there is no more data to
read, or until a zero-byte message block is encountered.
The read or readv then returns the number of bytes read, and
places the zero-byte message back on the stream to be
retrieved by the next read, readv, 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 or readv 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.
For regular disk files, if the O_DSYNC bit of the file
status flags is set, all I/O operations on the file descrip-
tor complete as defined by synchronized I/O data integrity
completion. If the O_SYNC bit of the file status flags is
set, all I/O operations on the file descriptor complete as
defined by synchronized I/O file integrity completion (refer
to the open(2) man page for the definitions of synchronized
I/O data and file integrity completions).
When attempting to read a file that has been opened in
direct mode (i.e. O_DIRECT is set) the buffer pointed to by
buf or iov->iov_base must be longword aligned. Additionally
nbyte or iov->iov_len must be a multiple of the longword
length (4 bytes) and less than the maximum physical transfer
size (see CX/UX Programmer's Guide for details). Lastly,
the file pointer associated with fildes should be aligned to
a multiple of the disk block size (1 Kbyte) before the read
request is issued.
Page 3 CX/UX Programmer's Reference Manual
read(2) read(2)
For pipes, FIFOs or character special devices, if the read
is interrupted by a signal, the number of bytes transferred
before the signal will be returned. If no bytes were
transferred, -1 will be returned and errno will be set to
EINTR.
For sockets, if an error occurs, the contents of buf are
undefined. If the read was interrupted by a signal, the
socket will be left in the same state as it was before the
call, and errno will be set to EINTR.
read and readv will fail if one or more of the following are
true:
[EAGAIN] Enforced record locking was enabled (see
chmod(2)), O_NDELAY or O_NONBLOCK was set,
and there was a write-lock owned by another
process.
[EAGAIN] The O_NONBLOCK flag is set for the file
descriptor and the process would be delayed
in the read operation because data is not
available.
[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] Enforced record locking was enabled, O_NDELAY
and O_NONBLOCK were clear, and a deadlock
condition was detected.
[EFAULT] Buf points outside the allocated address
space.
[EFAULT] The file is opened for direct mode and the
buffer is not aligned on a longword (4-byte)
boundary or the byte count is not a longword
multiple.
[EFAULT] The file is opened for direct mode and the
file pointer associated with fildes is not
aligned to a multiple of the disk block size
(1 Kbyte).
[ENOLCK] Enforced record locking was enabled and
Page 4 CX/UX Programmer's Reference Manual
read(2) read(2)
{LOCK_MAX} regions are already locked in the
system.
[EINTR] A signal was caught during the system call.
For a FIFO, pipe or character special device,
no data will have been transferred. For a
socket, it will be left in the same state as
it was before the call.
[EINVAL] Attempted to read from a stream linked to a
multiplexor.
[EIO] The process is in a background process group
and is attempting to read from its control-
ling terminal, and either the process is
ignoring or blocking the SIGTTIN signal or
the process group of the process is orphaned.
[ENXIO] The file is opened for direct mode and the
byte count was greater than the maximum phy-
sical transfer size.
[EWOULDBLOCK] The O_NDELAY flag is set and process would be
delayed in the read operation.
In addition, readv may return one of the following errors:
[EFAULT] Part of iov points outside the allocated
address space.
[EINVAL] Iovcnt was less than or equal to 0, or
greater than 16.
[EINVAL] One or more of the iov_len values in the iov
array was negative.
[EINVAL] The sum of the iov_len values in the iov
array overflowed a 32-bit integer.
A read or readv 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 and readv
will continue to operate normally until the stream head read
queue is empty. Thereafter, it will return 0.
RETURN VALUE
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 5 CX/UX Programmer's Reference Manual
read(2) read(2)
NOTE
The read function is defined in the 88open Binary and Object
Compatibility Standards (BCS/OCS) for use in BCS/OCS compli-
ant applications. Both functions are defined in the 88open
BCS/OCS Networking Supplements (BCSNS/OCSNS) for use in
BCS/OCS compliant networking applications. OCS/OCSNS-
defined functions may be accessed by passing OCS options to
cc(1) and ld(1).
SEE ALSO
bind(2), creat(2), dup(2), fcntl(2), ioctl(2), intro(2),
open(2), pipe(2), getmsg(2).
termio(7) and termios(7) in the CX/UX Administrator's Refer-
ence Manual.
Page 6 CX/UX Programmer's Reference Manual