read(2) SDK R4.11 read(2)
NAME
read, pread - read from an object
SYNOPSIS
#include <unistd.h>
ssizet read (fildes, buffer, nbyte)
int fildes;
void * buffer;
sizet nbyte;
ssizet pread (fildes, buffer, nbyte, offset)
int fildes;
void * buffer;
sizet nbyte;
offt offset;
where:
fildes An active, valid file descriptor.
buffer User data buffer.
nbyte Size (in bytes) of the read request.
offset Byte position in the object where the read is to begin.
DESCRIPTION
Read transfers nbyte bytes of data from the object associated with
fildes into the buffer pointed to by buffer. Pread does an atomic
seek and read, eliminating the necessity of using a locking mechanism
when both operations are desired and file descriptors are shared.
The behavior of pread is identical to read except for the handling of
the object's position attribute. Pread does not operate on pipe or
socket type objects.
For read, 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.
Pread does not use the position attribute of the object, nor does it
affect it. The I/O begins at the position in the object specified by
offset. An error is returned if the offset specifies a position in
the file past the two gigabyte limit on file sizes.
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.
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. Pread does not
affect the position attribute of the object in any way. 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.
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_NONBLOCK is set and there is a mandatory lock on the file
owned by a different process.
EAGAIN O_NONBLOCK is set and a read was attempted on an empty pipe
that another process has open for writing.
EAGAIN O_NONBLOCK is set and a read was attempted on a character
special device that had no data available (such as an
terminal).
EFAULT Buffer points outside the allocated address space.
EINVAL For pread, when an illegal file offset is specified. An
example of an illegal file offset would be an offset that
was past the two gigabyte file size limit.
EINTR A signal was caught during the system call.
EOPNOTSUPP
The pread system call does not support reading from a
socket.
ESPIPE Pread was attempted on a pipe type object.
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)