READ(2,L) AIX Technical Reference READ(2,L)
-------------------------------------------------------------------------------
read, readv, readx
PURPOSE
Reads from a file or socket.
SYNTAX
#include <sys/uio.h>
int read (d, buf, nbyte) int readx (d, buf, nbyte, ext)
int d; int d, ext;
char *buf; char *buf;
unsigned int nbyte; unsigned int nbyte;
int readv (d, iov, iovcnt)
int d;
struct iovec *iov;
unsigned int iovcnt;
DESCRIPTION
The read system call reads a set number of bytes into a buffer. The read
system call reads the number of bytes set by the nbyte parameter from the
object associated with the d parameter and places those bytes into the buffer
pointed to by the buf parameter.
The readv system call obtains data from the object associated with the d
parameter and reads this data into the buffers specified by the array of iovec
structures pointed to by the iov parameter.
The d parameter is a file descriptor obtained from a creat, open, dup, fcntl,
or pipe system call, or a socket descriptor from a socket or socketpair system
call.
The iovec structure is defined in the sys/uio.h header file, and it contains
the following members:
caddr_t iov_base;
int iov_len;
Each iovec entry specifies the base address and length of an area in memory
where data should be placed. The readv system call completely fills out an
area before moving to the next.
Processed November 7, 1990 READ(2,L) 1
READ(2,L) AIX Technical Reference READ(2,L)
On devices capable of seeking, the read starts at a position in the file given
by the file pointer associated with the d parameter. Upon return from the read
system call, 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.
When attempting to read from an empty pipe (or FIFO):
o Unless O_NDELAY or O_NONBLOCK is set, the read blocks until data is written
to the file or the file is no longer open for writing.
o If O_NDELAY is set, the read returns 0.
o If O_NONBLOCK is set, the read returns -1 and errno is set to EAGAIN.
When attempting to read a socket and no data is ready to be read:
o Unless O_NDELAY or O_NONBLOCK is set, the read blocks until data becomes
available.
o If O_NDELAY is set, the read returns 0.
o If O_NONBLOCK is set, the read returns -1 and errno is set to EAGAIN.
When attempting to read a file associated with a terminal that has no data
currently available:
o Unless O_NDELAY or O_NONBLOCK is set, the read blocks until data becomes
available.
o If O_NDELAY is set, the read returns 0.
o If O_NONBLOCK is set, the read returns -1 and errno is set to EAGAIN.
When attempting to read a regular file that supports enforcement mode record
locks, and all or part of the region to be read is currently locked by another
process:
o If O_NDELAY or O_NONBLOCK is set, then the read returns -1 and sets errno
to EAGAIN.
o If O_NDELAY and O_NONBLOCK are clear, then the read blocks the calling
process until the lock is released.
For more information about record locks, see "fcntl, flock, lockf."
The readx system call performs the same function as read, except that it
provides communication with character device drivers that require more
information or return more status than read can handle.
Processed November 7, 1990 READ(2,L) 2
READ(2,L) AIX Technical Reference READ(2,L)
For files, sockets, or special files with drivers that do not handle extended
operations, the readx system call does exactly what the read system call does,
and the ext parameter is ignored.
Each driver interprets the ext parameter in a device-dependent way, either as a
value or as a pointer to a communication area. The nonextended read system
call is equivalent to the extended readx system call with an ext parameter
value of 0. Drivers must apply reasonable defaults when the ext parameter
value is 0.
For directories, the ext parameter determines the format in which directory
entries should be returned:
If the value of ext is 0 (implied by the read system call), the format in
which directory entries are returned depends on the value of the real
directory read flag (see "ulimit").
o If the calling process does not have the real directory read flag set,
the buffer specified by the buf parameter is filled with an array of
directory entries truncated to fit the format of the direct structure
(see "dir"). This provides compatibility with programs written for UNIX
System V.
o If the calling process has the real directory read flag set, the buffer
specified by the buf parameter is filled with an image of the underlying
implementation of the directory.
If the value of ext is 1, the buffer specified by the buf parameter is
filled with consecutive directory entries in the format of a dirent
structure (see "dir"). This is used by the readdir library routine.
Other values of the ext parameter are reserved.
Note: On directories, the read, readv, and readx system calls start at the
position specified by the file pointer associated with the d parameter.
The value of this file pointer must either be 0 or a value which the
file pointer had immediately after a previous call to read or readx on
this directory. Upon return from the read or readx system call, the
file pointer is incremented by a number which may not correspond to the
number of bytes copied into the buffer.
RETURN VALUE
Upon successful completion for a file object, the read, readv, and readx system
calls return the number of bytes actually read and placed in the buffer; this
number may be less than the value of the nbyte parameter if the file is
associated with a communication line, or if the number of bytes left in the
file is less than the value of the nbyte parameter. A value of 0 is returned
when an end-of-file has been reached. (For information about communication
files, see "ioctlx, ioctl, gtty, stty" and "termio.")
Processed November 7, 1990 READ(2,L) 3
READ(2,L) AIX Technical Reference READ(2,L)
For a socket object, the read system call returns the number of bytes actually
read and placed into the buffer.
If the read, readv, or readx system call fails, a value of -1 is returned, and
errno is set to indicate the error.
ERROR CONDITIONS
The read, readv, and readx system calls fail if one or more of the following
are true:
EBADF d is not a valid file descriptor open for reading or a valid socket
descriptor.
EAGAIN An enforcement mode record lock is outstanding in the portion of the
file that is to be read.
EFAULT buf points to a location outside of the process's allocated address
space.
EDEADLK A deadlock would occur if the calling process were to sleep until the
region to be read was unlocked.
EINTR A signal was caught during the read or readv system call.
EINVAL The value of iovcnt was not between 1 and 16, inclusive.
EINVAL One 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.
EFAULT Part of the iov parameter points to a location outside of the
process's allocated address space.
EAGAIN The object is marked for non-blocking I/O (O_NONBLOCK), and no data
was ready to be read.
EINVAL An nbyte value of less than 0 is specified.
ENODEV The file specified is an invalid device for reading.
EIO A physical I/O error occurred.
EIO The process is in a background process group, attempting to read from
its controlling terminal and either the process is ignoring or
blocking the SIGTTIN signal or the process group of the calling
process is orphaned.
If the Transparent Computing Facility is installed on your system, read or
readx can also fail if one or more of the following are true:
Processed November 7, 1990 READ(2,L) 4
READ(2,L) AIX Technical Reference READ(2,L)
ESITEDN1 The file cannot be read because a site went down and either no other
copy of the file is available or the file is or was open for writing.
ESITEDN2 The operation was terminated because a site failed.
ENFILE The system inode table on another cluster site is out of space.
RELATED INFORMATION
In this book: "dup," "dup2," "fcntl, flock, lockf," "ioctlx, ioctl, gtty,
stty," "open, openx, creat," "pipe," "select," "socket," "socketpair,"
"fcntl.h," and "termio."
Processed November 7, 1990 READ(2,L) 5