read(2) DG/UX 5.4.2 read(2)
NAME
read - read from an object
SYNOPSIS
int read (fildes, buffer, nbyte)
int fildes;
char buffer[];
unsigned nbyte;
where:
fildes An active, valid file descriptor.
buffer User data buffer.
nbyte Size (in bytes) of the user data buffer.
DESCRIPTION
Read transfers nbyte bytes of data from the object associated with
fildes into the buffer pointed to by buffer.
If fildes refers to an object pointer having a current position
attribute, the read starts at a position in the object given by that
attribute. If the current position refers to a part of a file that
has never been written (i.e., a part of a file that was created by
seeking past the end of the file) then the value of the data is all
zeros.
If the object pointer has no position attribute, then the starting
read position depends on the type of object being read.
The behavior of the read call is affected by the object attribute
flag O_NDELAY (see open(2)) associated with fildes.
If the O_NDELAY flag is set and fildes refers to a file that has
mandatory record locking enabled and is currently write locked, the
call returns -1 and errno is set to EAGAIN. If O_NDELAY is clear,
the call blocks until the appropriate lock is removed or the call is
interrupted by a signal.
When attempting to read from an empty pipe (or fifo) the following
will occur: If no process has the pipe open for writing, 0 is
returned to indicate end-of-file. If some process has the pipe open
for writing, and O_NDELAY is set, 0 is returned. If some process has
the pipe open for writing, and O_NONBLOCK is set, -1 is returned and
errno is set to EAGAIN. If some process has the pipe open for
writing, and O_NDELAY is clear, the call 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 character special file that has no data
currently available, a read: (1) returns 0 if O_NDELAY is set (2)
returns -1 and sets errno to EAGAIN if O_NONBLOCK is set. For
character special files, behavior with both O_NDELAY and O_NONBLOCK
set is undefined.
Licensed material--property of copyright holder(s) 1
read(2) DG/UX 5.4.2 read(2)
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 ISRDOPT ioctl(2) request [see streamio(7)], and
can be tested with the IGRDOPT ioctl(2) request. In byte-stream
mode, read 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 retrieves data until they
have read nbyte bytes, or until they reach a message boundary. If
read 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 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 is discarded, and is
not available for a subsequent read or getmsg [see getmsg(2)].
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 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 ISRDOPT 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.
When read completes, the position attribute, if it exists, is
incremented by the number of bytes actually read. The access time
for the file is updated to reflect the time the read occurred, unless
the file resides on a read-only file system.
If an error occurs, the contents of buffer and any changes to the
object associated with fildes are defined by the object's type. The
default situation is that buffer and the object associated with
fildes are unchanged. This may not be the case for some errors on
some types of objects.
Licensed material--property of copyright holder(s) 2
read(2) DG/UX 5.4.2 read(2)
ACCESS CONTROL
Fildes must be open for reading.
RETURN VALUE
0..nbyte Completed successfully. The number of bytes actually
read is returned. The value 0 indicates the `end-of-
file' condition.
-1 An error occurred. errno is set to indicate the
error.
DIAGNOSTICS
Errno may be set to one of the following error codes:
EBADF Fildes is not a valid file descriptor open for reading.
EAGAIN O_NDELAY is set on the I/O channel and there is a mandatory
lock on the file owned by a different process.
EAGAIN A read was attempted on an empty pipe that another process
has open for writing.
EAGAIN A read was attempted on an I/O channel that had O_NDELAY
set, but there was no data ready to be read at the time of
the call.
EFAULT Buffer points outside the allocated address space.
EINTR A signal was caught during the system call.
EDEADLK fildes refers to a file that has mandatory record locking
enabled and the read would produce a deadlock condition.
See lockf(2) for a discussion of deadlock conditions.
SEE ALSO
creat(2), dup(2), dup2(2), fcntl(2), ioctl(2), open(2), pipe(2),
readv(2), select(2), socket(2), socketpair(2), termio(7).
Licensed material--property of copyright holder(s) 3