HP-UX Reference (11i v1 05/09) - 2 System Calls (vol 5)

r
read(2) read(2)
NAME
read, readv, pread - read from file
SYNOPSIS
#include <unistd.h>
ssize_t read(int fildes, void *buf, size_t nbyte);
ssize_t pread(int fildes, void *buf, size_t nbyte, off_t offset);
#include <sys/uio.h>
ssize_t readv(int fildes, const struct iovec *iov, int iovcnt);
DESCRIPTION
The read() function attempts to read nbyte bytes from the file associated with the open file descriptor,
fildes, into the buffer pointed to by buf.
If nbyte is 0,
read() will return 0 and have no other results.
On files that support seeking (for example, a regular file), the read() starts at a position in the file given
by the file offset associated with ldes. The file offset is incremented by the number of bytes actually read.
Files that do not support seeking, for example, terminals, always read from the current position. The value
of a file offset 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 will be returned. If the file refers to a device special file, the result of subsequent
read() requests is
implementation-dependent.
If the value of nbyte is greater than
{SSIZE_MAX} the result is implementation-dependent.
When attempting to read from an empty pipe or FIFO:
If no process has the pipe open for writing, read() will return 0 to indicate end-of-file.
If some process has the pipe open for writing and O_NONBLOCK is set, read() will return 1
and set
errno to [EAGAIN].
If some process has the pipe open for writing and O_NONBLOCK is clear, read() will block until
some data is written or the pipe is closed by all processes that had the pipe open for writing.
When attempting to read a file (other than a pipe or FIFO) that supports non-blocking reads and has no
data currently available:
If
O_NONBLOCK is set, read() will return a 1 and set errno to [EAGAIN].
If
O_NONBLOCK is clear, read() will block until some data becomes available.
The use of the O_NONBLOCK flag has no effect if there is some data available.
The read() function reads data previously written to a file. If any portion of a regular file prior to the
end-of-file has not been written, read() returns bytes with value 0. For example,
lseek() allows the
file offset to be set beyond the end of existing data in the file. If data is later written at this point, subse-
quent reads in the gap between the previous end of data and the newly written data will return bytes with
value 0 until data is written into the gap.
Upon successful completion, where nbyte is greater than 0,
read() will mark for update the st_atime field
of the file, and return the number of bytes read. This number will never be greater than nbyte. The value
returned may be less than nbyte if the number of bytes left in the file is less than nbyte, if the read()
request was interrupted by a signal, or if the file is a pipe or FIFO or special file and has fewer than nbyte
bytes immediately available for reading. For example, a read() from a file associated with a terminal
may return one typed line of data.
If a read() is interrupted by a signal before it reads any data, it will return 1 with errno set to
[EINTR].
If a read() is interrupted by a signal after it has successfully read some data, it will return the number of
bytes read.
A read() from a STREAMS file can read data in three different modes: byte-stream mode,
message-ondiscard mode, and message-discard mode. The default is byte-stream mode. This can be changed
using the I_SRDOPT ioctl() request, and can be tested with the I_GRDOPT ioctl().In
HP-UX 11i Version 1: September 2005 1 Hewlett-Packard Company Section 2265