 |
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.2, XNS4.0
pread(): POSIX.1c
readv(): XSH4.2, XNS4.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.
[XNS4.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 a 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 iovcount 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 mount -o
flag option noatimes, 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 mount -o flag option noatimes.
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
[XSH4.2] 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.
[XSH4.2] 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.
[XSH4.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() 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.
[XSH4.2] 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.
[XSH4.2] 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()
command. 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.
[XSH4.2] 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:
[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 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.
[XSH4.2] The value of the iovcount 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 filesystems mounted with the nfsv2 option, the
process attempted to read beyond the 2 gigabyte boundary.
[EISDIR] [Tru64 UNIX] Indicates either that the request for write access
to a file specified a directory name instead of a filename, or
that the function was trying to rename a directory as a file.
[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.
RELATED INFORMATION
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 |
|