read(2) read(2) NAME read, readv, pread, pread64 - read from file SYNOPSIS #include <unistd.h> ssize_t read(int fildes, void *buf, size_t nbyte); ssize_t pread(int fildes, void *buf, size_t nbyte, off_t offset); ssize_t pread64(int fildes, void *buf, size_t nbyte, off64_t offset); #include <sys/uio.h> ssize_t readv(int fildes, const struct iovec *iov, int iovcnt); DESCRIPTION read attempts to read nbyte bytes from the file associated with fildes into the buffer pointed to by buf. If nbyte is zero, read returns zero and has no other results. fildes is a file descriptor obtained from a creat, open, dup, fcntl, pipe, or ioctl system call. On devices capable of seeking, the read 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. 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. pread and pread64 are the same as read except that they do the equivalent of an lseek (for pread) or lseek64 (for pread64) offset bytes with the whence set to SEEK_SET before reading. On return from pread or pread64, the file pointer is unchanged. If fildes refers to a file incapable of seeking (a fifo or socket) then an error is returned and errno will be set to ESPIPE. readv performs the same action as read, but places the input data into the iovcnt buffers specified by the members of the iov array: iov[0], iov[1], ..., iov[iovcnt-1]. For readv, the iovec structure contains the following members: void *iov_base; ssize_t 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 buffer completely before proceeding to the next. On success, read and readv return the number of bytes actually read and placed in the buffer; There are many possible reasons why this number may be less than nbyte , without indicating end-of-file or an error. Some common reasons include when the file is associated with a communication line [see ioctl(2) and termio(7)], or when the number of bytes left in the file is less than nbyte, or when the file is a pipe or a special file, or the system call was interrupted. When end-of-file has been reached, read will return a value of 0. A value greater than 0, but less than nbyte , should not be construed as implying end-of-file, because many devices and even filesystems can return short counts for various reasons. read reads data previously written to a file. If any portion of an ordinary file prior to the end of file has not been written, read returns the number of bytes read as 0. For example, the lseek routine allows the file pointer to be set beyond the end of existing data in the file. If additional data is written at this point, subsequent reads in the gap between the previous end of data and newly written data return bytes with a value of 0 until data is written into the gap. When attempting to read from a file with O_DIRECT or FDIRECT set, -1 will be returned and errno will be set to EINVAL if nbyte or the current file position is not a multiple of the underlying device's blocksize, nbyte is too big or buf isn't properly aligned. See also F_DIOINFO in the fcntl(2) manual entry. When attempting to read from a file with O_DIRECT or FDIRECT set, the read data will by default come from an in-memory page if the data is locked in memory by a mlock(3C) command. If you wish to fail the read instead of having the data not be read directly from disk, set the systune(1M) variable xfs_dio_retry to zero (0) and the read will return -1 and errno will be set to EBUSY. When attempting to read from a file with O_RSYNC and O_SYNC set, the read will will wait to return until both the file data and file status to be physically updated. When attempting to read from a file with O_RSYNC and O_DSYNC set, the read will will wait to return until the file data has been physically updated. A read or readv from a STREAMS [see intro(2)] file can operate in three different modes: byte-stream mode, message-nondiscard mode, and message- discard mode. The default is byte-stream mode. This can be changed using the I_SRDOPT ioctl(2) request [see streamio(7)], and can be tested with the I_GRDOPT ioctl(2) request. In byte-stream mode, read and readv usually retrieve data from the stream until they have retrieved nbyte bytes, or until there is no more data to be retrieved. Byte-stream mode usually ignores message boundaries. In STREAMS message-nondiscard mode, read and readv retrieve data until they have read nbyte bytes, or until they reach a message boundary. If read or readv does not retrieve all the data in a message, the remaining data is replaced on the stream and can be retrieved by the next read or readv call. Message-discard mode also retrieves data until it has retrieved nbyte bytes, or it reaches a message boundary. However, unread data remaining in a message after the read or readv returns is discarded, and is not available for a subsequent read, readv, or getmsg [see getmsg(2)]. When attempting to read from a regular file with mandatory file/record locking set [see chmod(2)], and there is a write lock owned by another process on the segment of the file to be read: If O_NDELAY or O_NONBLOCK is set, read returns -1 and sets errno to EAGAIN. If O_NDELAY and O_NONBLOCK are clear, read sleeps until the blocking record lock is removed. When attempting to read from an empty pipe (or FIFO): If no process has the pipe open for writing, read returns 0 to indicate end-of-file. If some process has the pipe open for writing and O_NDELAY is set, read returns 0. If some process has the pipe open for writing and O_NONBLOCK is set, read returns -1 and sets errno to EAGAIN. If O_NDELAY and O_NONBLOCK are clear, read blocks until data is written to the pipe or the pipe is closed by all processes that had opened the pipe for writing. When attempting to read a file associated with a terminal or slave pty that has no data currently available: If O_NDELAY is set, read returns 0. If O_NONBLOCK is set, read returns -1 and sets errno to EAGAIN. If O_NDELAY and O_NONBLOCK are clear, read blocks until data becomes available. When attempting to read a file associated with a master pty or any other stream that is not a pipe or FIFO, or terminal, and that has no data currently available: If O_NDELAY or O_NONBLOCK is set, read returns -1 and sets errno to EAGAIN. If O_NDELAY and O_NONBLOCK are clear, read blocks until data becomes available. When attempting to read from a regular file in a DMAPI file system, if the DMAPI application will take a considerable time to make the file data available: If O_NDELAY or O_NONBLOCK is set, read returns -1 and sets errno to EAGAIN. If O_NDELAY and O_NONBLOCK are clear, read sleeps until the the DMAPI application has made the file data available. When reading from a STREAMS file, handling of zero-byte messages is determined by the current read mode setting. In byte-stream mode, read accepts data until it has read nbyte bytes, or until there is no more data to read, or until a zero-byte message block is encountered. read then returns the number of bytes read, and places the zero-byte message back on the stream to be retrieved by the next read or getmsg [see getmsg(2)]. In the two other modes, a zero-byte message returns a value of 0 and the message is removed from the stream. When a zero-byte message is read as the first message on a stream, a value of 0 is returned regardless of the read mode. A read or readv from a STREAMS file returns the data in the message at the front of the stream head read queue, regardless of the priority band of the message. Normally, a read from a STREAMS file can only process messages with data and without control information. The read fails if a message containing control information is encountered at the stream head. This default action can be changed by placing the stream in either control-data mode or control-discard mode with the I_SRDOPT ioctl(2). In control-data mode, control messages are converted to data messages by read. In control-discard mode, control messages are discarded by read, but any data associated with the control messages is returned to the user. read and readv fail if one or more of the following are true: EACCES fildes is open to a dynamic device and read permission is denied. EAGAIN Mandatory file/record locking was set, O_NDELAY or O_NONBLOCK was set, and there was a blocking record lock. EAGAIN Total amount of system memory available when reading via raw I/O is temporarily insufficient. EAGAIN No data is waiting to be read on a file associated with a tty device and O_NONBLOCK was set. EAGAIN No message is waiting to be read on a stream and O_NDELAY or O_NONBLOCK was set. EAGAIN A DMAPI application might delay a considerable time retrieving the file data, and O_NDELAY or O_NONBLOCK was set. EBADF fildes is not a valid file descriptor open for reading. EBUSY A direct I/O read was attempted on data that was locked in memory and could not be flushed to disk before doing the I/O. EBADMSG Message waiting to be read on a stream is not a data message. EDEADLK The read was going to go to sleep and cause a deadlock to occur. EFAULT buf points outside the allocated address space. EINTR A signal was caught during the read or readv system call and no bytes had been read. EINVAL Attempted to read from a stream linked to a multiplexor. EINVAL fildes has O_DIRECT or FDIRECT set and either the buffer alignment, current file pointer alignment or read request size is not valid for direct I/O. See also F_DIOINFO on fcntl(2). 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 either the process is ignoring or blocking the SIGTTIN signal or the process group of the process is orphaned. EIO fildes is open to a device that is in the process of closing. EIO fildes has O_DIRECT or FDIRECT set and the number of bytes requested by read or readv is greater than the number of bytes between the current file pointer position and end of file. ENOLCK The system record lock table was full, so the read or readv could not go to sleep until the blocking record lock was removed. ENXIO The device associated with fildes is a block special or character special file and the value of the file pointer is out of range. ESPIPE pread or pread64 was called on a file incapable of seeking. In addition, readv may return one of the following errors: EFAULT iov points outside the allocated address space. EINVAL iovcnt was less than or equal to 0 or greater than {IOV_MAX}. {IOV_MAX} is the maximum number of iovec structures that one process has available for use with readv. The value {IOV_MAX} can be obtained from a call to sysconf() [see sysconf(3C)]. EINVAL The sum of the iov_len values in the iov array overflowed a 32-bit integer. ETIMEDOUT The object of the read is located on a remote system which is not available [see intro(2)]. A read from a STREAMS file also fails if an error message is received at the stream head. In this case, errno is set to the value returned in the error message. If a hangup occurs on the stream being read, read continues to operate normally until the stream head read queue is empty. Thereafter, it returns 0. SEE ALSO intro(2), creat(2), dup(2), fcntl(2), getmsg(2), ioctl(2), open(2), pipe(2), recv(3N), streamio(7), sysconf(3C), termio(7), pty(7M). NOTES read updates the time of last access (see stat(2)) of the file. DIAGNOSTICS On success a non-negative integer is returned indicating the number of bytes actually read. Otherwise, a -1 is returned and errno is set to indicate the error. Page 6