READ(2)
NAME
read, readv − read input
SYNOPSIS
int read (fildes, buf, nbyte)
int fildes;
char ∗buf;
unsigned nbyte;
#include <sys/types.h>
#include <sys/uio.h>
int readv (fildes, iov, iovcnt)
int fildes;
struct iovec *iov;
int iovcnt;
DESCRIPTION
Read attempts to read nbyte bytes from the file associated with the file descriptor into the buffer pointed to by buf. Readv performs the same action but scatters the input data into the iovcnt buffers specified by the elements of the iovec array: iov[0], iov[1], ..., iov[ iovcnt - 1].
For readv, the iovec structure is defined as:
struct iovec {
| 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. Readv always fills one area completely before proceeding to the next area. The iovec array can be at most MAXIOV long.
On devices capable of seeking, the read starts at a position in the file given by the file offset associated with fildes. Upon return from read, the file offset is incremented by the number of bytes actually read.
Devices incapable of seeking always read from the current position. The value of a file offset associated with such a device is undefined.
When attempting to read from a regular file with enforcement-mode file and record locking set (see chmod(2)), and the segment of the file to be read is blocked by a write lock owned by another process, the behavior is determined by the O_NDELAY and O_NONBLOCK file status flags:
If O_NDELAY or O_NONBLOCK is set, the read function returns −1 and errno is set to EAGAIN.
If O_NDELAY and O_NONBLOCK are clear, the read function does not return until the blocking write lock is removed.
When attempting to read from an empty pipe (or FIFO):
If O_NONBLOCK is set, the read returns −1 and errno is set to EAGAIN.
If O_NDELAY is set, the read returns a 0.
If O_NDELAY and O_NONBLOCK are clear, the read blocks 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_NONBLOCK is set, the read returns −1 and errno is set to EAGAIN.
If O_NDELAY is set, the read returns a 0.
If O_NDELAY and O_NONBLOCK are clear, the read blocks until data becomes available.
RETURN VALUE
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
• the number of bytes left in the file is less than nbyte bytes.
When an end-of-file is reached, a value of 0 is returned Otherwise, a −1 is returned and errno is set to indicate the error.
ERRORS
Read fails if one of the following conditions is true:
[EBADF] Fildes is not a valid file descriptor open for reading.
[EINTR] A signal was caught during the read system call.
[EAGAIN] Enforcement-mode file and record locking is set, O_NDELAY or O_NONBLOCK is set, and there is a blocking write lock.
[EDEADLK] A resource deadlock would occur as a result of this operation (see lockf(2) and fcntl(2)).
[EFAULT] Buf points outside the allocated address space. The reliable detection of this error is implementation dependent.
[EIO] The process is in a background process group and is attempting to read from its controlling terminal, and either the process is ignoring or blocking the SIGTTIN signal or the process group of the process is orphaned.
[EISDIR] An attempt was made to read a directory on an NFS file system using the read system call.
[ENOLCK] The system record lock table is full, preventing the read from sleeping until the blocking write lock is removed.
In addition, readv can return one of the following errors:
[EFAULT]
Iov_base or iov points outside of the allocated address space. The reliable detection of this error is implementation dependent.
[EINVAL]
Iovcnt is less then or equal to 0, or greater than MAXIOV.
[EINVAL]
The sum of iov_len values in the iov array exceeded UINT_MAX (see <limits.h>).
EXAMPLES
Assuming a process opened a file for reading, the following call to read(2) reads BUFSIZ bytes from the file into the buffer pointed to by mybuf:
#include <stdio.h> /* include this for BUFSIZ definition */
char mybuf[BUFSIZ];
int nbytes, fildes;
nbytes = read (fildes, mybuf, BUFSIZ);
WARNINGS
Record locking might not be enforced by the system, depending on the setting of the file’s mode bits (see lockf(2)).
The character-special devices, and raw disks in particular, apply constraints on how read can be used. See the specific Section (7) entries for details on particular devices.
Check all references to signal(5) for appropriateness on systems that support sigvector(2). Sigvector(2) can affect the behavior described on this page.
In general, avoid using read to get the contents of a directory; use the readdir library routine, see directory(3C).
DEPENDENCIES
NFS
When obtaining the contents of a directory on an NFS file system, the readdir library routine must be used; see directory(3C). Read returns with an error if used to read a directory using NFS.
AUTHOR
Read was developed by HP, AT&T, and the University of California, Berkeley.
SEE ALSO
creat(2), dup(2), fcntl(2), ioctl(2), lockf(2), open(2), pipe(2), select(2), ustat(2), tty(7), directory(3C).
STANDARDS CONFORMANCE
read: SVID2, XPG2, XPG3, POSIX.1, FIPS 151-1
Hewlett-Packard Company — HP-UX Release 7.0: Sept 1989