Manpage of READ

READ

Section: Linux Fast-STREAMS System Calls (2)
Updated: 2008-10-31
Index Return to Main Contents

NAME

read - read from a file descriptor

SYNOPSIS

#include <unistd.h>
ssize_t read(int fd, void *buf, size_t nbytes);

ARGUMENTS

fd: The file descriptor from which to read.
buf: The buffer into which to read the bytes.
nbytes: The maximum number of bytes to read.

DESCRIPTION

read() attempts to read up to nbytes bytes from file descriptor fd into the buffer starting at buf.

If nbytes is zero, read() returns zero and has no other results. If nbytes is greater than SSIZE_MAX, the result is unspecified.

A read() request that is interrupted by a signal before any data is transferred to the user fails, returns minus one (-1), and sets errno(3) to [EINTR].

A read() request that is interrupted by a signal after data has already been transferred to the user, terminates and returns the number of bytes read.

A read() from a STREAMS file shall return the data in the message at the front of the STREAM head read queue, regardless of the priority of the message.

STREAM head Read Modes

A read() from a STREAMS file can read data in three different modes: byte-stream mode, message-nondiscard mode and message-discard mode. The default is byte-stream mode. The current mode for a particular STREAMS file can be changed using the I_SRDOPT command to ioctl(2s), and can be examined using the I_GRDOPT command.

*: In byte-stream mode, read() shall retrieve data from the STREAMS file until as many bytes as were requested are transferred, or until there is no more data to be retrieved. Byte-stream mode ignores message boundaries.
*: In STREAMS message non-discard mode, read() shall retreive data until as many bytes are were requested are transferred, or until a message boundary is reached. If read() does not retreival all the data in a message, the remaining data shall be left on the STREAM, and can be retrieved by the next read(), getmsg(2) or getpmsg(2s) call.
*: Message-discard mode also retrieves data until as many bytes as were requested are transferred, or a message boundary is reached. However, unread data remaining in a message after the read() call returns shall be discarded, and shall not be available to a subsequent read(), getmsg() or getpsmg() call.

How read() handles zero-byte STREAMS messages is determined by the current read mode setting:

*: In byte-stream mode, read() shall accept 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() function shall then return the number of bytes read, and place the zero-byte message back on the STREAM to be retrieved by the next read(), getmsg(2) or getpmsg(2s) call.
*: In message-nondiscard mode or message-discard mode, a zero-byte message shall return zero (0) and the message shall be removed from the STREAM.
*: Regardless of the read mode, whenever a zero-byte message is read as the first message on a STREAM, the message shall be removed from the STREAM and zero (0) shall be returned.

STREAMS Read Control Modes

A read() from a STREAMS file can handle control parts in STREAMS messages in three different modes: control-normal mode, control-data mode and control-discard mode. The default is control-normal mode. (Older versions of STREAMS only supported control-normal mode.) The current control mode for a particular STREAMS file can be changes using the I_SRDOPT(7) command to ioctl(2s), and can be examined using the I_GRDOPT(7) command.

How read() handles STREAMS message containing control parts depends on the current read control mode setting:

*: In control-normal mode, a read() from a STREAMS file can only process messages that contain a data part but do not contain a control part. The read() shall fail, return minus one (-1) and set errno(3) to [EBADMSG], if a message containing a control part is encountered at the STREAM head.
*: In control-data mode, read() shall convert any control part to data and pass it to the application before passing any data part originally present in the same message.
*: In control-discard mode, read() shall discard message control parts but return to the process any data part in the message.

Also, read() shall fail if the STREAM head had processed an asynchronous error before the call. In this case, the value of errno(3) shall not reflect the result of read(), but reflect the prior error. If a hangup occurs on the STREAM being read, read() shall continue to operate normally until the STREAM head read queue is empty. Thereafter, it shall return zero (0).

Marked Messages

STREAMS messages can be marked by a downstream module or driver in support of TCP's out-of-band data. Once marked, a message sent to the stream head causes the stream head to remember the message. A user may check to see if the message on the front of its stream head read queue is marked with the I_ATMARK(7) command to ioctl(2s). If a user is reading data from the stream head and there are multiplex messages on the read queue, and one of those messages is marked, read() terminates when it reaches the marked message and returns the data only up to the marked message. The rest of the data can be obtained with successive reads.

When read() encounters a marked message and data has already been transferred, the read terminates with the amount of data already read. The marked message is kept on the STREAM head to be read by a subsequent read(), getmsg() or getpmsg() call. The resulting short read is an indication to the caller that a marked message could exist on the STREAM head read queue. (Short reads can also result from a zero-length data message, or from a delimited message.) When a short read occurs, the user should test for a marked message using the ANYMARK flag of the I_ATMARK(7) command to ioctl(2s). A subsequent read() will consume the marked message. If a marked message exists, there is the possibility that there is also a marked message following the marked message. This can be checked with the LASTMARK flag of the I_ATMARK(7) comand to ioctl(2s).

Synchronous and Asynchronous I/O

How read() handles asynchronous input-output using the O_NDELAY (or O_NONBLOCK) file status flags depends on the semantics setting of the STREAM head. The STREAM head can be set for STREAMS semantics for O_NDELAY, or it can be set for old TTY semantics for O_NDELAY. This setting can only be changed by a downstream module or driver by issuing a M_SETOPTS(9) message to the STREAM head with the SO_NDELON or STR_NDELOFF flags set. The application has no method for examining the setting of semantics for the STREAM head and must rely on prior knowledge of the behaviour of the modules or driver in a particular STREAM.

Regardless of the semantics used at the STREAM head, when O_NDELAY (or O_NONBLOCK) are clear, a call to read() will block awaiting the requested number of bytes, nbytes, or a message boundary, or a zero-length message. The read() request might still terminate early and return and error or the number of bytes transferred when a signal is received or an error is encountered.

When O_NDELAY (or O_NONBLOCK) file status flags are set on fd, the behaviour of read() depends on the semantics setting at the STREAM head:

*: When the STREAM head is set to STREAMS semantics for O_NDELAY, and the requested number of bytes are not immediately available to be read from the STREAM head read queue, read() terminates and returns the number of bytes that could be transferred. If no bytes could be transferred, read() fails, returns minus one (-1), and sets errno(3) to [EAGAIN].
*: When the stream head is set to old TTY semantics for O_NDELAY, and the requested number of bytes are not immediately available to be read from the STREAM head read queue, read() terminates and returns the number of bytes that could be transferred. If no bytes could be transferred, read() terminates and returns zero (0).

When attempting to read from a STREAMS file that has no data currently available:

*: If the STREAM head is set for STREAMS semantics for O_NDELAY, and O_NONBLOCK (or O_NDELAY) is set, read() will fail, return minus one (-1), and set errno(3) to [EAGAIN].
*: If the STREAM head is set for old TTY semantics for O_NDELAY, and O_NDELAY (or O_NONBLOCK) is set, read() will terminate and return zero (0).
*: If O_NONBLOCK (or O_NDELAY) is clear, read() shall block the calling thread until some data becomes available.
*: The use of the O_NONBLOCK (or O_NDELAY) flag has no effect if there is some data available at the time of the call to read().

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

*: If no process has the FIFO, or other end of the pipe, open for writing, read() shall return zero (0) to indicate end-of-file.
: This is consistent with hangup behaviour for STREAMS files.
*: If some process has the FIFO, or the other end of the pipe, open for writing and O_NONBLOCK (or O_NDELAY) is set, read() shall return minus one (-1) and set errno(3) to [EAGAIN].
: This is consistent with STREAMS semantics for O_NDELAY behaviour for STREAMS files.
*: If some process has the FIFO, or the other end of the pipe, open for writing and O_NONBLOCK (or O_NDELAY) is clear, read() shall block the calling thread until some data is written or the FIFO, or the other end of the pipe, is closed by all processes that had the FIFO, or the other end of the pipe, open for writing.

RETURN VALUE

On success, the number of bytes read is returned (zero indicates end of file), and the file position is advanced by this number. It is not an error if this number is smaller than the number of bytes requested; this may happen for example because fewer bytes are actually available right now (maybe because we were close to end-of-file, or because we are reading from a pipe, or from a terminal), or because read() was interrupted by a signal. On error, -1 is returned, and errno is set appropriately. In this case it is left unspecified whether the file position (if any) changes.

ERRORS

[EINTR]: The call was interrupted by a signal before any data was read.
[EAGAIN]: Non-blocking I/O has been selected using O_NONBLOCK and no data was immediately available for reading.
[EIO]: I/O error. This will happen for example when the process is in a background process group, tries to read from its controlling tty, and either it is ignoring or blocking SIGTTIN or its process group is orphaned. It may also occur when there is a low-level I/O error while reading from a disk or tape.
[EISDIR]: fd refers to a directory.
[EBADF]: fd is not a valid file descriptor or is not open for reading.
[EINVAL]: fd is attached to an object which is unsuitable for reading.
[EFAULT]: buf is outside your accessible address space.

When fd refers to a STREAMS file or a STREAMS-based pipe or FIFO, the following additional error conditions can occur:

[EBADF]: fd is not a valid open file descriptor, or is not opened for reading.
[EINVAL]: fd refers to a STREAM that is linked (directly or indirectly) downstream from a multiplexing driver.
[EIO]: fd refers to a STREAM that is closed or closing.
[EAGAIN]: fd is set for non-blocking operation using the O_NDELAY (or O_NONBLOCK) file status flags, the STREAM head is set for STREAMS semantics for O_NDELAY, and no data was immediately available to be read.
[ETIME]: The calling process blocked for an excessive period of time.

Also, if the STREAM head receives an asyncrhonous error message (M_ERROR(9)) indicating a read error, the error returned in errno(3) will be the error received in the error message.

When fd refers to a STREAMS file, the following additional error conditions can occur:

[ENXIO]: fd refers to a STREAM that has received a hangup message (M_HANGUP(9)).

When fd refers to a STREAMS-based pipe or FIFO, the following additional error conditions can occur:

[EPIPE]: fd refers to a STREAMS-based pipe that has received a hangup message (M_HANGUP(9)).
[EPIPE]: fd refers to a STREAMS-based pipe and the other end of the pipe has disconnected.
[EPIPE]: fd refers to a STREAMS-based pipe or FIFO and the other end of the pipe or FIFO has closed or is closing.
[ESTRPIPE]: fd refers to a STREAMS-based pipe or FIFO, the other end of the pipe or FIFO has hung up, or is closing, or has closed, or there remain no writers and there is no data available to be read on the STREAM head read queue.

Other errors may occur, depending on the object connected to fd. POSIX allows a read that is interrupted after reading some data to return -1 (with errno set to EINTR) or to return the number of bytes already read.

NOTICES

The behaviour of multiple concurrent reads on the same STREAM, pipe, FIFO, or terminal device is unspecified.

RESTRICTIONS

On NFS file systems, reading small amounts of data will only update the time stamp the first time, subsequent calls may not do so. This is caused by client side attribute caching, because most if not all NFS clients leave atime updates to the server and client side reads satisfied from the client's cache will not cause atime updates on the server as there are no server side reads. UNIX semantics can be obtained by disabling client side attribute caching, but in most situations this will substantially increase server load and decrease performance.

COMPATIBILITY

read() is compatible with SVID[1], XID[2], SUSv2[3], SUSv3/POSIX[4], and implementations based on SVR 4.2[5], including AIX®, HP-UX®, IRIX®, LiS, MacOT®, OSF/1®, Solaris®, SUPER-UX®, UnixWare®, UXP/V®, with the following portability considerations:

---
---: There is some differences between the way that POSIX[4] describes blocking operation in byte-stream mode and the way that SVR 4[6] describes blocking operation in byte-stream mode.
: POSIX says that in byte-stream mode the STREAM reads up to nbytes of data, or until there is no more data left on the stream, or a zero-length message is encountered, (or a signal or error condition interrupts the read). POSIX also says that in byte-stream mode a zero-length message terminates the read but that if data has already been transferred that the zero-length message is placed back on the read queue.
: SVR 4 says that in byte-stream mode the STREAM reads up to nbytes of data, or a zero-length message is encountered. SVR 4 says that in byte-stream mode a zero-length message terminates the read (a short read) but does not say that the zero-length message is placed back on the stream. SVR 4 also says that an M_READ(9) message is generated downstream when there is insufficient data at the STREAM head to satisfy the read() request, and that, when VMIN=0 and VTIME=0, ldterm(4) transforms M_READ(9) messages into zero-length M_DATA(9) messages to signal the STREAM head to return with a short read.
: AIX®[7] and OSF/1®[8] provide a special RFILL mode similar to RNORM except that the buffer is completely filled. This behaviour is somewhere between the POSIX and SVR 4 behavior. Other implementations, and particularly UnixWare®[9] state that an M_READ(9) message contains the number of bytes requested by the read and is only sent downstream when there is no data at the STREAM head, and that ldterm(4) transforms the M_READ(9) message into a M_DATA(9) message containing the requested data if there is a data available. (Otherwise, it presumably discards the M_READ(9) message!) (Note that it is possible to have the STREAM head allocate a buffer associated with the M_READ(9) message sufficient to hold the number of bytes necessary to allow the M_READ(9) message to be transformed into an M_DATA(9) message without having to reallocate a block, allowing the M_READ(9) to be processed easily within a module or driver qi_putp(9) procedure.)
: LiS[10] terminates on a zero-length message but does not place a zero-length message back onto the STREAM head read queue when data has already been transferred and in byte-stream mode, but it terminates after reading data when there is no more data to read. This seems half POSIX (terminate with short read when data no longer available, generate M_READ(9) only for no data condition before blocking) and half SVR 4 (do not requeue zero-length data messages in byte-stream mode) behavior.
: These are several rather different behaviours for read() when in byte-stream mode. POSIX behaviour centers around placing a zero-length message back on the queue in byte-stream mode. SVR 4 behaviour centers around not placing the message back.
: Under Linux Fast-STREAMS, the POSIX behavior for zero-length messages is followed if the STREAM head is not marked for delimited messages or the zero-length message is not marked or delimited and follows the SVR 4 behavior if the STREAM head is set for delimited messages and the message is delimited, and whenever a message is marked. This seems to be a good compromise. Also, when the Linux Fast-STREAMS STREAM head generates an M_READ(9) message, it allocates a buffer with sufficient size to hold the requested data so that it can be easily transformed into a M_DATA(9) message without reallocating a message data block.
: Portable STREAMS modules and drivers will expect the POSIX behaviour unless the STREAM head has been explicitly set by the downstream module or driver to delimited messages by sending an M_SETOPTS(9) message to the STREAM head with the SO_DELIMON flag set, and send zero-length messages with the MSGDELIM flag set, in which case they will expect the SVR 4 behaviour.
: Portable STREAMS applications programs must expect that a read() might terminate early with a read count less than nbytes, and that it might block and be interrupted mid-read.
---: Although POSIX[4] specifies that if an interrupt occurs during a read after data has already been transferred, that the call terminates and returns the number of bytes read, it is questionable under what conditions this could happen. The POSIX behaviour is to terminate with the number of bytes read when no more data is waiting to be read at the STREAM head. This means that the POSIX implementation would not block after blocking for the initial message, so how can it receive a signal subsequently?
: SVR 4[6] specifies that read waits for all requested bytes and therefore an implementation would block each time that there is no data waiting to be read and could, therefore, be interrupted in the middle of transferring data while waiting for more data.
: LiS[10] follows the POSIX behavior in this regard.
: These behaviors are somewhat contradictory too.
: When Linux Fast-STREAMS is following the POSIX behaviour as described above, it will not block mid-read; when following the SVR 4 behaviour, it can block mid-read.
: Portable STREAMS applications programs must expect that a short read could result from an error on the STREAM in the middle of the read, or that the read can be interrupted in the middle as a result of a signal.
---: The behaviour of read() when restarting signals are used is also confusing. Linux Fast-STREAMS uses the error number [ERESTARTSYS] as a signal to the C library that the call can be restarted.
---: AIX®[7] and OSF/1®[8] provides the additional RFILL read mode and the additional RPROTCOMPRESS control mode, but these are incompatible with the i386 ABI. RFILL requests that the read() call block until nbytes is satsified (similar to the SVR 4 discussion above). RPROTCOMPRESS compress identical data messages into a compressed result. Although this might be useful for SS7 MTP Level 2, it is not portable.
: Portable STREAMS modules, drivers and application programs will not use the RFILL or RPROTCOMPRESS read modes.
---
---

Linux Fast-STREAMS used to recognize the "invalid" buffer length to read() used by LiS to emulate the __NR_getpmsg system call. This is no longer the case. Linux Fast-STREAMS (as with current versions of LiS)[10], uses the I_GETPMSG command to ioctl(2s) to emulate the getpmsg(2s) system call.

CONFORMING TO

SVr4, SVID, AT&T, POSIX, X/OPEN, BSD 4.3

HISTORY

UNIX®Version 7.

REFERENCES

[1]: SVID, System V, Interface Definition, Fourth Edition.
[2]: XBD Issue 5, X/Open System Interface Definitions, Issue 5, OpenGroup, Open Group Publication. <http://www.opengroup.org/onlinepubs/>
[3]: SUS Version 2, Single UNIX Specification, OpenGroup, Open Group Publication. <http://www.opengroup.org/onlinepubs/>
[4]: SUS Version 3, Single UNIX Specification, OpenGroup, Open Group Publication. <http://www.opengroup.org/onlinepubs/>
[5]: SVR 4.2 CR, UNIX® System V Release 4.2 Command Reference Manual, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[6]: Magic Garden, The Magic Garden Explained: The Internals of UNIX® System V Release 4 / An Open Systems Design, 1994, (Australia), B. Goodheart, J. Cox, Prentice Hall. [ISBN 0-13-098138-9] Section 7.9.6 "Reading from a stream", p. 480..
[7]: AIX® 5L Version 5.1, AIX 5L Version 5.1 Documentation, 2001, (Boulder, Colorado), Internatonal Business Machines Corp., IBM. <http://publibn.boulder.ibm.com/>
[8]: Digital® UNIX (OSF/1.2), Digital UNIX Documentation Library, 2003, (Palo Alto, California), Digital Equipment Corporation, Hewlett-Packard Company. <http://www.true64unix.compaq.com/docs/>
[9]: UnixWare® 7.1.3, UnixWare 7.1.3 (OpenUnix 8) Documentation, 2002, (Lindon, Utah), Caldera International, Inc., Caldera. <http://uw713doc.sco.com/>
[10]: LIS 2.18, Linux STREAMS (LiS) 2.18.6 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>