read(2) read(2)NAME read, readv - reads from a file SYNOPSIS #include <sys/types.h> #include <sys/uio.h> int read(fildes, buf, nbytes) int fildes; char *buf; unsigned nbytes; int readv(fildes, iov, iovcnt) int fildes; struct iovec *iov; int iovcnt; DESCRIPTION read attempts to read nbytes bytes from the file associated with fildes into the buffer pointed to by buf. readv performs 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 file descriptor fildes is obtained from a creat, open, dup, fcntl, pipe, or socket system call. 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 an area completely before proceeding to the next. On devices capable of seeking, the reading starts at a position in the file given by the file pointer associated with fildes. On return from read, the file pointer is incremented by the number of bytes actually read. On devices incapable of seeking, reading always starts from the current position. The value of a file pointer associated with such a file is undefined. On successful completion, read and readv return the number of bytes actually read and placed in the buffer; this number may be less than nbytes if the file is associated with a January 1992 1
read(2) read(2)communication line (see ioctl(2), socket(2N), and termio(7)) or if the number of bytes left in the file is less than nbytes. A value of 0 is returned when an end-of-file has been reached. If nbyte is 0, read returns 0 and has no other result. When attempting to read from an empty pipe (or FIFO) and if O_NDELAY is set, the read returns 0. if O_NDELAY is 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 and if O_NDELAY is set, the read returns 0. if O_NDELAY is clear, the read blocks until data becomes available. When attempting to read from an empty pipe (or FIFO) and if O_NONBLOCK is set, the read returns -1 and sets errno to EAGAIN. if O_NONBLOCK is clear, the read blocks until some data is written or the pipe is closed by all processes that had the pipe open for writing. if no process has the pipe open for writing, the read returns 0 to indicate end-of-file. When attempting to read a file associated with a terminal that has no data currently available and if O_NONBLOCK is set, the read returns -1 and set errno to EAGAIN. if O_NONBLOCK is clear, the read blocks until data becomes available. STATUS MESSAGES AND VALUES On successful completion, a non-negative integer is returned indicating the number of bytes actually read. If the process compatibility flag COMPAT_SYSCALLS is set (see setcompat(2)), as in the POSIX environment, and read is interrupted by a signal after successfully reading some data, it returns the number of bytes read. Otherwise, a -1 is returned and errno is set to EINTR to indicate the error. 2 January 1992
read(2) read(2)When attempting to read from a stream that has no data currently available and if O_NDELAY is set, read returns -1 and errno is set to ENODATA. If O_NDELAY is clear, read blocks until data becomes available. read and readv will fail if one or more of the following is true: EIO A physical I/O error has occurred or the process is in a background process group and is attempting to read from its controlling terminal and the process is ignoring or blocking SIGTTIN or the process group of the process is orphaned. ENXIO The device associated with the file descriptor is a block-special or character-special file and the value of the file pointer is out of range. EWOULDBLOCK The file was marked for nonblocking I/O, and no data was ready to be read. EBADF The file descriptor fildes is not valid and open for reading. EFAULT buf points outside the allocated address space. EINTR A signal was caught during the read system call. ENODATA A read from a stream was attempted when no data was available and O_NDELAY was set. In addition, readv may return one of the following errors: EINVAL iovcnt was less than or equal to 0, or greater than 16. 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. January 1992 3
read(2) read(2)SEE ALSO creat(2), fcntl(2), ioctl(2), open(2), pipe(2), socket(2N), setcompat(2), termio(7) 4 January 1992