NAME

read − read from file

SYNOPSIS

int read (fildes, buf, nbyte)
int fildes;
char ∗buf;
unsigned nbyte;

DESCRIPTION

fildes is a file descriptor obtained from a creat(2), open(2), dup(2), fcntl(2), or pipe(2) system call.

read attempts to read nbyte bytes from the file associated 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 position.  The value of a file pointer associated with such a file is undefined. 

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(2) and termio(7)], 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 [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 request [see streamio (7)], and can be tested with the I_GRDOPT ioctl. In byte-stream mode, read retrieves data from the stream until it has retrieved nbyte bytes, or until there is no more data to be retrieved.  Byte-stream mode ignores messsage boundaries. 

In STREAMS message-nondiscard mode, read retrieves data until it has read nbyte bytes, or 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(2) 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(2)], and there is a blocking (i.e. owned by another process) write lock on the segment of the file to be read:

If O_NDELAY is set, the read returns a −1 and sets errno to EAGAIN. 

If O_NDELAY is clear, the read sleeps until the blocking record lock is removed. 

When attempting to read from an empty pipe (or FIFO):

If O_NDELAY is set, the read returns a 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:

If O_NDELAY is set, the read returns a 0. 

If O_NDELAY 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 O_NDELAY is set, the read returns a −1 and sets errno to EAGAIN. 

If O_NDELAY 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.  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.  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 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. 

read fails if one or more of the following are true:

[EAGAIN] Mandatory file/record locking was set, O_NDELAY 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 message waiting to be read on a stream and O_NDELAY 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 message. 

[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 multiplexor. 

[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. 

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

creat(2), dup(2), fcntl(2), getmsg(2), ioctl(2),intro(2), open(2), pipe(2), streamio(7), termio(7)

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. 

September 02, 1992