 |
Index for
Section 2 |
|
 |
Alphabetical
listing for R |
|
 |
Bottom of
page |
|
read(2)
NAME
read, pread, readv - read from a file
SYNOPSIS
#include <unistd.h>
ssize_t read(
int filedes,
void *buffer,
size_t nbytes );
ssize_t pread(
int filedes,
void *buffer,
size_t nbytes,
off_t offset) );
#include <sys/uio.h>
ssize_t readv(
int filedes,
const struct iovec *iov,
int iov_count );
STANDARDS
Interfaces documented on this reference page conform to industry standards
as follows:
read(): XSH4.0, XSH4.2, XNS5.0
pread(): POSIX.1, XSH5.0
readv(): XSH4.2, XNS5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
filedes
Identifies the file from which data is read.
buffer
Points to the buffer to receive data that is being read.
nbytes
Specifies the number of bytes to read from the file associated with the
filedes parameter.
offset
Specifies the desired start position inside the file associated with
the filedes parameter.
iov Points to an array of iovec structures that identifies the buffers into
which the data is to be placed. The iovec structure is defined in the
<sys/uio.h> header file and contains the following members:
void *iov_base;
size_t iov_len;
iov_count
Specifies the number of iovec structures pointed to by the iov
parameter.
DESCRIPTION
The read() function attempts to read nbytes of data from the file
associated with the filedes parameter into the buffer pointed to by the
buffer parameter.
If the value of nbytes is 0 (zero), the read() function returns 0 and has
no other results.
[XNS5.0] If filedes refers to a socket, a read() request is equivalent to
a recv() request with no flags set.
The pread() function performs the same action as read(), except that it
reads from a given position in the file (specified by the offset parameter)
without changing the file pointer. The first three arguments to pread() are
the same as for read(). The fourth argument to pread(), offset, specifies
the desired position inside the file. An attempt to perform a pread() on a
file that is incapable of seeking results in an error.
The readv() function performs the same action as the read() function, but
scatters the input data into the buffers specified by the array of iovec
structures pointed to by the iov parameter. The iov_count parameter
specifies the number of buffers pointed to by the iov parameter. Each iovec
entry specifies the base address and length of an area in memory where data
should be placed. The iov_count parameter is valid if greater than 0
(zero) and less than or equal to IOV_MAX, which is defined in the
<sys/limits.h> header file. The readv() function always fills an area
completely before proceeding to the next.
On regular files and devices capable of seeking, the read() function starts
at a position in the file given by the file pointer associated with the
filedes parameter. Upon return from the read() function, the file pointer
is incremented by the number of bytes actually read.
Devices that are incapable of seeking (for example, terminals) always read
from the current position. The value of a file pointer associated with such
a file is undefined.
No data transfer will occur past the current end-of-file. If the starting
position is at or after the end-of-file, 0 (zero) is returned.
When attempting to read from an empty pipe (FIFO) the read() and pread()
functions behave as follows:
· If no process has the pipe open for writing, the function returns 0
(zero) to indicate end-of-file.
· If some process has the pipe open for writing and O_NONBLOCK is set,
the function returns a value of -1 and sets errno to [EAGAIN].
· If some process has the pipe open for writing and O_NONBLOCK is clear,
the function will block until some data is written or the pipe is
closed by all processes that opened the pipe for writing.
· [Tru64 UNIX] If some process has the pipe open for writing and
O_NDELAY is set, the function returns a value of -1 and sets errno to
[EAGAIN].
· [Tru64 UNIX] If some process has the pipe open for writing and
O_NDELAY is clear, the function will block until some data is written
or the pipe is closed by all processes that opened the pipe for
writing.
When attempting to read a file (other than a pipe) that supports
nonblocking reads and has no data currently available, the read() and
pread() functions behave as follows:
· If O_NONBLOCK is set, the function returns -1 and sets errno to
[EAGAIN].
· If O_NONBLOCK is clear, the function will block until data becomes
available.
· [Tru64 UNIX] If O_NDELAY is set and the file is a serial device, the
function returns -1 and sets errno to [EAGAIN].
· [Tru64 UNIX] If O_NDELAY is set and the file is a STREAMS device, the
function returns 0 and sets errno to 0.
· [Tru64 UNIX] If O_NDELAY is clear, the function will block until data
becomes available.
· [Tru64 UNIX] If both O_NDELAY and O_NONBLOCK are set and the file is
a STREAMS device, the function returns -1 and sets errno to [EAGAIN].
The behavior of O_NONBLOCK takes precedence over the behavior of
O_NDELAY.
[Tru64 UNIX] The use of the O_NONBLOCK flag has no effect if there is some
data available.
[Tru64 UNIX] When attempting to read from a regular file with enforcement
mode record locking enabled and all or part of the region to be read is
currently locked by another process (a write lock or exclusive lock), the
read() and pread() functions behave as follows:
· If O_NDELAY and O_NONBLOCK are clear, the function blocks the calling
process until the lock is released, or the function is terminated by a
signal.
· If O_NDELAY or O_NONBLOCK is set, the function returns -1 and sets
errno to [EAGAIN].
The read() and pread() functions read data previously written to a file. If
any portion of a regular file prior to the end-of-file has not been
written, the function returns bytes with value 0 (zero).
Upon successful completion, where nbytes is greater than 0 (zero), the
read() or pread() function marks the st_atime field of the file for update
and returns the number of bytes actually read and placed in the buffer.
This number will never be greater than nbytes. The value returned may be
less than nbytes if the number of bytes left in the file is less than
nbytes, if the read() or pread() request was interrupted by a signal, or if
the file is a pipe (FIFO) or special file and has fewer than nbytes bytes
immediately available for reading. For example, a read() from a file
associated with a terminal may return one typed line of data.
[Tru64 UNIX] For AdvFS or UFS files that are mounted with the -o noatimes
option of the mount command, file access time changes are made in memory,
but are not flushed to disk until other file modifications occur. This
behavior can improve server response time by decreasing the number of disk
I/O operations. However, the behavior violates POSIX standards and
jeopardizes the integrity of file access times. See mount(8) for more
information about the -o noatimes option.
If a read() or pread() function is interrupted by a signal before it reads
any data, it returns -1 with errno set to [EINTR].
If a read() or pread() function is interrupted by a signal after it has
successfully read some data, it returns the number of bytes read.
Upon successful completion, readv() marks for update the st_atime field of
the file.
Reading Data From STREAMS Files
Function behavior discussed in this section is defined for compilation
environments that support XSH4.2 and higher revisions of the XSH
specification.
A read() or pread() 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 I_SRDOPT
ioctl() request (see the streamio(7) reference page) and can be tested with
the I_GRDOPT ioctl(). In byte-stream mode, read() or pread() retrieves data
from the STREAM until it has retrieved nbytes bytes or until there is no
more data to be retrieved. Byte-stream mode ignores message boundaries.
In STREAMS message-nondiscard mode, read() or pread() retrieves data until
it has read nbytes bytes or until it reaches a message boundary. If the
read() or pread() 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(), pread(), or getmsg() call. Message-discard mode also retrieves data
until it has retrieved nbytes bytes or until it reaches a message boundary.
However, unread data remaining in a message after the read() or pread()
returns is discarded and is not available for a subsequent read(), pread(),
readv(), or getmsg() call.
When reading from a STREAMS file, handling of zero-byte messages is
determined by the current read mode setting. In byte-stream mode, read() or
pread() accepts data until it has read nbytes bytes, until there is no more
data to read, or until a zero-byte message block is encountered. The read()
or pread() function then returns the number of bytes read and places the
zero-byte message back on the STREAM to be retrieved by the next read(),
pread(), or getmsg() call. 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() or pread() 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.
By default, STREAMS are in control-normal mode, in which a read() or
pread() from a STREAMS file can only process data messages that contain a
data part but do not contain a control part. The read() or pread() fails if
a message containing a control part 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 I_SRDOPT ioctl() request. In
control-data mode read() or pread() converts any control part to data and
passes it to the application before passing any data part originally
present in the same message. In control-discard mode, read() or pread()
discards message control parts but returns, to the process, any data part
in the message.
In addition, read(), pread(), and readv() will fail if the STREAM head
processed an asynchronous error before the call. In this case, the value of
errno does not reflect the result of read(), pread(), and readv(), but
reflects the prior error. If a hangup occurs on the STREAM being read,
read() or pread() continues to operate normally until the STREAM head read
queue is empty. Thereafter, it returns 0 (zero).
NOTES
[Tru64 UNIX] For compatibility with earlier releases, values for iov_len
that are greater than or equal to 2^63 will be treated as zero.
[Tru64 UNIX] The read(), pread(), and readv() functions, which suspend the
calling process until the request is completed, are redefined so that only
the calling thread is suspended.
[Tru64 UNIX] When debugging a module that includes the readv() function,
use _Ereadv to refer to the readv() call.
When a read(), pread(), write(), or pwrite() system call on a pipe is
interrupted by a signal and no bytes have been transferred through the
pipe, a value of -1 is returned and errno is set to [EINTR]. This behavior
is different from previous releases in which both read() and write() either
restarted the transfer or set errno to [EINTR], depending on the setting of
the SA_RESTART flag for the interrupting signal.
As a result of this change, applications must now either handle the [EINTR]
return or block any expected signals for the duration of the read(),
pread(), write(), or pwrite() operation.
RETURN VALUES
Upon successful completion, the read(), pread(), and readv() functions
return the number of bytes actually read and placed into buffers.
The system guarantees to read the number of bytes requested only if the
descriptor references a regular file that has the same number of bytes left
before the end-of-file.
If the read(), pread(), and readv() functions fail, a value of -1 is
returned, errno is set to indicate the error, and the content of the buffer
pointed to by the buffer parameter is indeterminate.
End-of-Media Handling for Tapes
If reading goes beyond the "early warning" EOT indicator while this
indicator is disabled, the read(), pread(), and readv() functions will
return the number of bytes actually read and placed into the buffer. The
read(), pread(), and readv() functions return a value of -1, if:
· Attempting to read past the "real" EOT.
· Attempting to read past "early warning" EOT indicator while this
indicator is enabled.
Refer to mtio(7) for information on enabling and disabling "early warning"
EOT.
End-of-Media Handling for Disks
Disk end-of-media handling is POSIX-conformant. Attempting to read at or
beyond the end of a partition returns a value of 0. A partial read returns
the number of bytes actually read.
Note: A partial read is a request that spans the end of a partition.
ERRORS
The read(), pread(), and readv() functions set errno to the specified
values for the following conditions. Note that conditions marked [XSH4.2]
apply to compilation environments that support XSH4.2 and higher versions
of the XSH specification.
[EAGAIN]
The O_NONBLOCK flag is set on this file and the process would be
delayed in the read(), pread(), or readv() operation.
[Tru64 UNIX] No message is waiting to be read on a STREAM and the
O_NDELAY or O_NONBLOCK flag is set.
[Tru64 UNIX] An enforcement mode record lock is outstanding in the
portion of the file that is to be read.
[EBADF]
The filedes parameter is not a valid file descriptor open for reading.
[EBADMSG]
[XSH4.2] The file is a STREAM file that is set to control-normal mode
and the message waiting to be read includes a control part.
[Tru64 UNIX] The message waiting to be read on a STREAM is not a data
message system call.
[Tru64 UNIX] The message that is waiting to be read is not a data
message.
[EDEADLK]
[Tru64 UNIX] Enforcement mode file locking is enabled, O_NDELAY and
O_NONBLOCK are clear, and a deadlock condition is detected.
[EFAULT]
[Tru64 UNIX] The buffer or part of the iov value points to a location
outside the allocated address space of the process.
[EINTR]
A read on a pipe (FIFO) is interrupted by a signal and no bytes have
been transferred through the pipe.
[EINVAL]
[XSH4.2] The STREAM or multiplexer referenced by filedes is linked
(directly or indirectly) downstream from a multiplexer.
[XSH4.2] The sum of the iov_len values in the iov array overflowed an
ssize_t buffer.
[XSH4.2] The value of the iov_count parameter was less than or equal
to 0, or greater than IOV_MAX.
[Tru64 UNIX] The file position pointer associated with the filedes
parameter was negative.
[Tru64 UNIX] The sum of the iov_len values in the iov array was
negative or overflowed a 32-bit integer.
[Tru64 UNIX] The requested operation attempted to read from a STREAM
linked to a multiplexer.
[EIO]
[XSH4.2] A physical I/O error occurred.
The process is a member of a background process attempting to read from
its controlling terminal, the process is ignoring or blocking the
SIGTTIN signal, or the process group is orphaned.
[ENOLCK]
[Tru64 UNIX] The file has enforcement mode file locking set and
allocating another locked region would exceed the configurable system
limit of NLOCK_RECORD.
[ENOSPC]
[Tru64 UNIX] An attempt was made to read past the "early warning" EOT
while this indicator was enabled.
[ENXIO]
The device specified by the file descriptor parameter filedes is a
block special character or a character special file, and the file
pointer value is out of range.
In addition, the pread() function fails and the file pointer remains
unchanged if the following is true:
[ESPIPE]
The file specified by filedes is associated with a pipe (FIFO).
For NFS file access, if the read() or pread() function fails, errno may
also be set to one of the following values:
[EBADRPC]
[Tru64 UNIX] Indicates that the client has requested more data than
the server agreed to provide.
[EFBIG]
[Tru64 UNIX] For file systems mounted with the mount command's -o
nfsv2 option, the process attempted to read beyond the 2 gigabyte
boundary.
[EISDIR]
For an NFS client, fildes identifies a directory that resides on an
NFS server. In this case, the application must use readdir() or
getdirentries() to read the directory.
[ENFILE]
[Tru64 UNIX] Indicates either that the system file table is full or
that too many files are currently open in the system.
[ENOBUFS]
[Tru64 UNIX] Indicates insufficient resources, such as buffers, to
complete the call. Typically, a call used with sockets has failed due
to a shortage of message or send/receive buffer space.
[ESTALE]
[Tru64 UNIX] Indicates a stale NFS file handle. An opened file was
deleted by the server or another client, a client cannot open a file
because the server has unmounted or unexported the remote directory, or
the directory that contains an opened file was either unmounted or
unexported by the server.
SEE ALSO
Functions: fcntl(2), creat(2), dup(2), ioctl(2), mtio(7), open(2), pipe(2),
poll(2), socket(2), socketpair(2), termios(4), streamio(7), opendir(3)
lockf(3)
Standards: standards(5)
|
Index for
Section 2 |
|
|
Alphabetical
listing for R |
|
 |
Top of
page |
|