read(2)
NAME
read, readv − read input
SYNOPSIS
#include <unistd.h>
size_t read(int fildes, void *buf, size_t nbyte);
#include <sys/uio.h>
ssize_t readv(
int fildes,
const struct iovec *iov,
size_t 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, read() returns −1 and errno is set to EAGAIN.
• If O_NDELAY and O_NONBLOCK are clear, read() does not return until the blocking write lock is removed.
When attempting to read from an empty pipe (or FIFO):
• If no process has the pipe open for writing, the read returns a 0.
• If some process has the pipe open for writing and 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 some process has the pipe open for writing and 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 0.
• If O_NDELAY and O_NONBLOCK are clear, the read blocks until data becomes available.
If read() is interrupted by a signal after it has successfully read some data, it returns the number of bytes actually read and placed in the buffer before the interrupt occurred. If read() is interrupted before any data is successfully read, read() returns −1 and sets errno to EINTR.
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.
• read() was interrupted by a signal after it had successfully read some, but not all of the data requested.
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 any of the following conditions are encountered:
[EBADF] fildes is not a valid file descriptor open for reading.
[EINTR] A signal was caught before any data was transferred (see sigvector(2)).
[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. 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.
[EIO] An I/O error occurred while reading from the device corresponding to fildes.
[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 defined in <limits.h> (see limits(5)).
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)).
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() 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(): AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1
Hewlett-Packard Company — HP-UX Release 9.0: August 1992