--- read.2 --- read(2) read(2) NAME read, pread, readv - Read from a file. SYNOPSIS #include ssize_t read( int filedes, void *buffer, size_t nbytes); PARAMETERS filedes Identifies the file from which data is read. buffer Points to the buffer to receive data read. nbytes Specifies the number of bytes to read from the file associated with the filedes parameter. DESCRIPTION The read() function attempts to read nbytes of data from the file associ- ated with the filedes parameter into the buffer pointed to by the buffer parameter. If the value of nbytes is 0 (zero), the read() function returns 0 and has no other results. [XPG4-UNIX] If filedes refers to a socket, read() is equivalent to recv() with no flags set. On regular files and devices capable of seeking, the read() function starts at a position in the file given by the file pointer associated with the filedes parameter. Upon return from the read() function, the file pointer is incremented by the number of bytes actually read. Devices that are incapable of seeking always read from the current posi- tion. The value of a file pointer associated with such a file is undefined. No data transfer will occur past the current end-of-file. If the starting position is at or after the end-of-file, 0 (zero) is returned. When attempting to read from an empty pipe (or FIFO) the read() and pread() functions behave as follows: + If no process has the pipe open for writing, the function returns 0 (zero) to indicate end-of-file. + If some process has the pipe open for writing and O_NONBLOCK is set, the function returns a value of -1 and sets errno to [EAGAIN]. + If some process has the pipe open for writing and O_NONBLOCK is clear, the function will block until some data is written or the pipe is closed by all processes that had opened the pipe for writing. + [Digital] If some process has the pipe open for writing and O_NDELAY is set, the function returns a value of -1 and sets errno to [EAGAIN]. + [Digital] If some process has the pipe open for writing and O_NDELAY is clear, the function will block until some data is written or the pipe is closed by all processes that had opened the pipe for writing. When attempting to read a file (other than a pipe or FIFO) that supports nonblocking reads and has no data currently available, the read() and pread() functions behave as follows: + If O_NONBLOCK is set, the function returns -1 and sets errno to [EAGAIN]. + If O_NONBLOCK is clear, the function will block until data becomes available. + [Digital] If O_NDELAY is set, and the file is a serial device, the function returns -1 and sets errno to [EAGAIN]. + [Digital] If O_NDELAY is set, and the file is a STREAMS device, the function returns 0 and sets errno to 0. + [Digital] If O_NDELAY is clear, the function will block until data becomes available. The use of the O_NONBLOCK flag has no effect if there is some data avail- able. [Digital] The use of the O_NDELAY flag has no effect if there is some data available. [Digital] When attempting to read from a regular file with enforcement mode record locking enabled, and all or part of the region to be read is currently locked by another process (a write lock or exclusive lock), the read() and pread() functions behave as follows: + If O_NDELAY and O_NONBLOCK are clear, the function blocks the calling process until the lock is released, or the function is terminated by a signal. + If O_NDELAY or O_NONBLOCK is set, the function returns -1 and sets errno to [EAGAIN]. The read() and pread() functions read data previously written to a file. If any portion of a regular file prior to the end-of-file has not been written, the function returns bytes with value 0 (zero). [Digital] If the file is a character special device that has been the tar- get of a stopio() function, subsequent reads from the device will terminate with an [EBADF] error and the process delivers a SIGHUP signal. Upon successful completion, where nbytes is greater than 0 (zero), the read() or pread() function marks the st_atime field of the file for update and returns the number of bytes actually read and placed in the buffer. This number will never be greater than nbytes. The value returned may be less than nbytes if the number of bytes left in the file is less than nbytes, if the read() or pread() request was interrupted by a signal, or if the file is a pipe or FIFO or special file and has fewer than nbytes bytes immediately available for reading. For example, a read() from a file asso- ciated with a terminal may return one typed line of data. If a read() or pread() function is interrupted by a signal before it reads any data, it returns -1 with errno set to [EINTR]. If a read() or pread() function is interrupted by a signal after it has successfully read some data, it returns the number of bytes read. The readv() function performs the same action as the read() function, but scatters the input data into the buffers specified by the array of iovec structures pointed to by the iov parameter. The iov_count parameter speci- fies the number of buffers pointed to by the iov parameter. Each iovec entry specifies the base address and length of an area in memory where data should be placed. The iovcount parameter is valid if greater than 0 (zero) and less than or equal to IOV_MAX, which is defined in the sys/limits.h header file. The readv() function always fills an area completely before proceeding to the next. Upon successful completion, readv() marks for update the st_atime field of the file. Reading Data From STREAMS Files [XPG4-UNIX] A read() or pread() from a STREAMS 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() request (see the streamio(7) reference page), and can be tested with the I_GRDOPT ioctl(). In byte-stream mode, read() or pread() retrieves data from the STREAM until it has retrieved nbytes bytes, or until there is no more data to be retrieved. Byte-stream mode ignores message boundaries. [XPG4-UNIX] In STREAMS message-nondiscard mode, read() or pread() retrieves data until it has read nbytes bytes, or until it reaches a message boun- dary. If the read() or pread() does not retrieve all the data in a mes- sage, the remaining data are replaced on the STREAM, and can be retrieved by the next read(), pread(), or getmsg() call. Message-discard mode also retrieves data until it has retrieved nbytes bytes, or it reaches a message boundary. However, unread data remaining in a message after the read() or pread() returns are discarded, and are not available for a subsequent read(), pread(), readv(), or getmsg() call. [XPG4-UNIX] When reading from a STREAMS file, handling of zero-byte mes- sages is determined by the current read mode setting. In byte-stream mode, read() or pread() accepts data until it has read nbytes bytes, or until there is no more data to read, or until a zero-byte message block is encountered. The read() or pread() function then returns the number of bytes read, and places the zero-byte message back on the STREAM to be retrieved by the next read(), pread(), or getmsg() call. 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. [XPG4-UNIX] A read() or pread() 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. [XPG4-UNIX] By default, STREAMS are in control-normal mode, in which a read() or pread() from a STREAMS file can only process data messages that contain a data part but do not contain a control part. The read() or pread() fails if a message containing a control part 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() command. In control-data mode read() or pread() converts any control part to data and passes it to the application before passing any data part ori- ginally present in the same message. In control-discard mode, read() or pread() discards message control parts but returns to the process any data part in the message. [XPG4-UNIX] In addition, read(), pread(), and readv() will fail if the STREAM head had processed an asynchronous error before the call. In this case, the value of errno does not reflect the result of read(), pread(), and readv(), but reflects the prior error. If a hangup occurs on the STREAM being read, read() or pread() continues to operate normally until the STREAM head read queue is empty. Thereafter, it returns 0 (zero). NOTES [Digital] The read(), pread(), and readv() functions, which suspend the calling process until the request is completed, are redefined so that only the calling thread is suspended. [Digital] When debugging a module that includes the readv() function and for which _XOPEN_SOURCE_EXTENDED has been defined, use _Ereadv to refer to the readv() call. See standards(5) for information on when the _XOPEN_SOURCE_EXTENDED macro is defined. When a read(), pread(), write(), or pwrite() system call on a pipe is interrupted by a signal and no bytes have been transferred through the pipe, a value of -1 is returned and errno is set to [EINTR]. This behavior is different from previous releases, when both read() and write() either restarted the transfer or set errno to [EINTR], depending on the setting of the SA_RESTART flag for the interrupting signal. As a result of this change, applications must now either handle the [EINTR] return or block any expected signals for the duration of the read(), pread(), write(), or pwrite() operation. RETURN VALUES Upon successful completion, the read(), pread(), and readv() functions return the number of bytes actually read and placed into buffers. The sys- tem guarantees to read the number of bytes requested only if the descriptor references a regular file that has the same number of bytes left before the end-of-file. If the read(), pread(), and readv() functions fail, a value of -1 is returned, errno is set to indicate the error, and the content of the buffer pointed to by the buffer parameter is indeterminate. End-of-Media Handling for Tapes If reading goes beyond the "early warning" EOT indicator while this indica- tor is disabled, the read(), pread(), and readv() functions will return the number of bytes actually read and placed into the buffer. The read(), pread(), and readv() functions return a value of -1, if: + Attempting to read past the "real EOT". + Attempting to read past "early warning" EOT indicator while this indi- cator is enabled. Refer to mtio(7) for information on enabling and disabling "early warning" EOT. End-of-Media Handling for Disks Disk end-of-media handling is POSIX-conformant. Attempting to read at or beyond the end of a partition returns a value of 0. A partial read returns the number of bytes actually read. Note: A partial read is a request which spans the end of a partition. ERRORS The read(), pread(), and readv() functions set errno to the specified values for the following conditions. [EAGAIN] The O_NONBLOCK flag is set on this file and the process would be delayed in the read(), pread(), or readv() operation. [Digital] No message is waiting to be read on a STREAM and the O_NDELAY or O_NONBLOCK flag is set. [Digital] An enforcement mode record lock is outstanding in the portion of the file that is to be read. [EBADF] The filedes parameter is not a valid file descriptor open for reading. [Digital] The read addresses a file descriptor that references a character device that has previously been the subject of a suc- cessful stopio() call. [EBADMSG] [XPG4-UNIX] The file is a STREAM file that is set to control- normal mode and the message waiting to be read includes a control part. [Digital] The message waiting to be read on a STREAM is not a data message system call. [Digital] The message that is waiting to be read is not a data message. [EDEADLK] [Digital] Enforcement mode file locking is enabled, O_NDELAY and O_NONBLOCK are clear, and a deadlock condition is detected. [EFAULT] [Digital] The buffer or part of the iov points to a location outside of the allocated address space of the process. [EINTR] A read on a pipe is interrupted by a signal and no bytes have been transferred through the pipe. [EINVAL] [XPG4-UNIX] The STREAM or multiplexer referenced by filedes is linked (directly or indirectly) downstream from a multiplexer. [XPG4-UNIX] The sum of the iov_len values in the iov array over- flowed an ssize_t. [XPG4-UNIX] The value of the iovcount parameter was less than or equal to 0, or greater than IOV_MAX. [Digital] The file position pointer associated with the filedes parameter was negative. [Digital] The sum of the iov_len values in the iov array was negative or overflowed a 32-bit integer. [Digital] The requested operation attempted to read from a STREAM linked to a multiplexer. [EIO] [XPG4-UNIX] A physical I/O error has occurred. The process is a member of a background process attempting to read from its controlling terminal, the process is ignoring or blocking the SIGTTIN signal, or the process group is orphaned. [ENOLCK] [Digital] The file has enforcement mode file locking set and allocating another locked region would exceed the configurable system limit of NLOCK_RECORD. [ENOSPC] [Digital] An attempt was made to read past the "early warning" EOT while this indicator was enabled. [ENXIO] The device specified by the file descriptor parameter filedes is a block special character or a character special file, and the file pointer value is out of range. In addition, the pread() function fails and the file pointer remains unchanged if the following is true: [ESPIPE] The file specified by filedes is associated with a pipe or FIFO. For NFS file access, if the read() or pread() function fails, errno may also be set to one of the following values: [EBADRPC] [Digital] Indicates that the client has requested more data than the server agreed to provide. [EFBIG] [Digital] For filesystems mounted with the nfsv2 option, the pro- cess attempted to read beyond the 2 gigabyte boundary. [EISDIR] [Digital] Indicates either that the request was for a write access to a file but the specified filename was actually a direc- tory, or that the function was trying to rename a directory as a file. [ENFILE] [Digital] Indicates either that the system file table is full, or that there are too many files currently open in the system. [ENOBUFS] [Digital] Indicates insufficient resources, such as buffers, to complete the call. Typically, a call used with sockets has failed due to a shortage of message or send/receive buffer space. [ESTALE] [Digital] Indicates a stale NFS file handle. An opened file was deleted by the server or another client; a client cannot open a file because the server has unmounted or unexported the remote directory; or the directory that contains an opened file was either unmounted or unexported by the server. RELATED INFORMATION Functions: fcntl(2), creat(2), dup(2), ioctl(2), getmsg(2), lockf(3), lseek(2), mtio(7), open(2), pipe(2), poll(2), socket(2), socketpair(2), termios(4), streamio(7), stopio(3), opendir(3) lockf(3) Standards: standards(5) delim off