read(2) read(2)NAME read, readv - read from file SYNOPSIS int read(fildes, buf, nbytes) int fildes; char *buf; unsigned nbytes; #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 nbytes 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 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 posi- tion in the file given by the file pointer associated with fildes. On return from read, the file pointer is increment- ed 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 associat- ed 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 communication line (see ioctl(2), socket(2N), and termio(7)) April, 1990 1
read(2) read(2)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 oth- er 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 be- comes 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 be- comes available. RETURN VALUE On successful completion, a non-negative integer is returned indicating the number of bytes actually read. If the pro- cess compatibility flag COMPAT_SYSCALLS is set (see setcom- pat(2)), as in the POSIX environment, and read is interrupt- ed by a signal after successfully reading some data, it re- turns the number of bytes read. Otherwise, a -1 is returned and errno is set to EINTR to indicate the error. 2 April, 1990
read(2) read(2)ERRORS 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 are true: [EIO] A physical I/O error has occurred or the pro- cess is in a background process group and is attempting to read from its controlling termi- nal 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. SEE ALSO creat(2), fcntl(2), ioctl(2), open(2), pipe(2), socket(2N), setcompat(2), termio(7). April, 1990 3