read(S) 6 January 1993 read(S) Name read - read from file Syntax cc . . . -lc int read (fildes, buf, nbyte) int fildes; char *buf; unsigned nbyte; Description fildes is a file descriptor obtained from a creat(S), open(S), dup(S), Lfcntl(S), or pipe(S) system call. The read system call attempts to read nbyte bytes from the file associ- ated with fildes into the buffer pointed to by buf. On devices capable of seeking, the read starts at a position in the file given by the file pointer associated with fildes. Upon 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 posi- tion. The value of a file pointer associated with such a file is unde- fined. 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(S) and termio(M)), or if the number of bytes left in the file is less than nbyte bytes. A value of 0 is returned when an end-of-file has been reached. A read 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 ISRDOPT ioctl request, (see streamio(STR)) and can be tested with the IGRDOPT ioctl. In byte-stream mode, read retrieves data from the stream until it has retrieved nbyte bytes, or until no more data can be retrieved. Byte-stream mode ignores message boundaries. In STREAMS message-nondiscard mode, read retrieves data until it has read nbyte bytes, or until it reaches a message boundary. If the read does not retrieve all the data in a message, the remaining data are replaced on the stream, and can be retrieved by the next read or getmsg(S) 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 returns are discarded and are not available for a subsequent read or getmsg. When attempting to read from a regular file with mandatory file/record locking set (see chmod(S)), and there is a blocking (that is, owned by another process) write lock on the segment of the file to be read: + If ONONBLOCK is set, the read returns a -1 and set errno to EAGAIN. + If ONONBLOCK is clear, the read sleeps until the blocking record lock is removed. When attempting to read from an empty pipe (or FIFO): + If ONONBLOCK is set, the read returns a 0. + If ONONBLOCK 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: + If ONONBLOCK is set, the read returns a 0. + If ONONBLOCK is clear, the read blocks until data becomes available. When attempting to read a file associated with a stream that has no data currently available: + If ONONBLOCK is set, the read returns a -1 and set errno to EAGAIN. + If ONONBLOCK is clear, the read blocks until data becomes 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. The read system call 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. 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 regard- less of the read mode. A read from a STREAMS file can only process data messages. It cannot process any type of protocol message and fails if a protocol message is encountered at the stream head. The read system call fails if one or more of the following are true: [EAGAIN] Mandatory file/record locking was set, ONONBLOCK was set, and there was a blocking record lock. [EAGAIN] Total amount of system memory available when reading via raw IO is temporarily insufficient. [EAGAIN] No message waiting to be read on a stream and ONONBLOCK flag set. [EBADF] fildes is not a valid file descriptor open for reading. [EBADMSG] Message waiting to be read on a stream is not a data mes- sage. [EDEADLK] The read was going to go to sleep and cause a deadlock situation to occur. [EFAULT] buf points outside the allocated address space. [EINTR] A signal was caught during the read system call. [EINVAL] Attempted to read from a stream linked to a multiplexer. [EIO] A physical I/0 error has occurred. [ENOLCK] The system record lock table was full, so the read could not go to sleep until the blocking record lock was removed. [ENOLINK] fildes is on a remote machine and the link to that machine is no longer active. [ENXIO] Mandatory file/record locking was set, ONONBLOCK was set, and there was a blocking record lock. Diagnostics Upon successful completion 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. See also creat(S), dup(S), fcntl(S), getmsg(S), ioctl(S), open(S), pipe(S) Standards conformance read is conformant with: AT&T SVID Issue 2; X/Open Portability Guide, Issue 3, 1989; Intel386 Binary Compatibility Specification, Edition 2 (iBCSe2); IEEE POSIX Std 1003.1-1990 System Application Program Interface (API) [C Language] (ISO/IEC 9945-1); and NIST FIPS 151-1.