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

r
read(2) read(2)
HP-UX EXTENSIONS
DESCRIPTION
For readv(), the iovec
structure is defined in /usr/include/sys/uio.h
.
For ordinary files, if the
O_RSYNC|O_DSYNC file status flag is set, the calling process blocks until the data
being read and all file attributes required to retrieve the data are the same as their image on disk. Writes
pending on the data to be read are executed before returning to the calling process. If the
O_RSYNC|O_SYNC file status flag is set, the behavior is identical to that for
O_RSYNC|O_DSYNC with
this addition: all file attributes changed by the read operation (including access time, modification time and
status change time) must also be the same as their image on disk. For block special files, if either the
O_RSYNC|O_DSYNC or O_RSYNC|O_SYNC status flag is set, the calling process blocks until the data
being read is an image of the data on the disk. Writes pending on the data to be read are executed before
returning to the calling process.
When attempting to read from a regular file with enforcement-mode file and record locking set (see
chmod(2)), and the segment of the file to be read is blocked by a write lock owned by another process, the
behavior is determined by the
O_NDELAY and O_NONBLOCK file status flags:
• If O_NDELAY or O_NONBLOCK is set, read() returns −1 and errno is set to [EAGAIN].
• If O_NDELAY and O_NONBLOCK are clear, read() does not return until the blocking write
lock is removed.
When attempting to read from an empty pipe (or FIFO):
• If no process has the pipe open for writing, the read returns a 0.
• If some process has the pipe open for writing and O_NONBLOCK is set, the read returns −1 and
errno is set to [EAGAIN].
• If O_NDELAY is set, the read returns a 0.
• If some process has the pipe open for writing and O_NDELAY and O_NONBLOCK are clear, the
read blocks until data is written to the file or the file is no longer open for writing.
When attempting to read a file associated with a tty that has no data currently available:
• If
O_NDELAY is set, the read returns 0.
• If O_NDELAY and O_NONBLOCK are clear, the read blocks until data becomes available.
RETURN VALUE
Upon successful completion, read() returns the number of bytes actually read and placed in the buffer;
this number may be less than nbyte if:
• The file is associated with a communication line (see ioctl(2) and termio(7)), or
• The number of bytes left in the file is less than nbyte bytes.
•
read() was interrupted by a signal after it had successfully read some, but not all of the data
requested.
When an end-of-file is reached, a value of 0 is returned. Otherwise, a −1 is returned and errno is set to
indicate the error.
ERRORS
read() fails if any of the following conditions are encountered:
[EBADF] fildes is not a valid file descriptor open for reading.
[EINTR] A signal was caught before any data was transferred (see sigvector (2)).
[EAGAIN] Enforcement-mode file and record locking is set, O_NDELAY or
O_NONBLOCK is
set, and there is a blocking write lock.
[EDEADLK] A resource deadlock would occur as a result of this operation (see lockf(2) and
fcntl(2)).
[EFAULT] buf points outside the allocated address space. Reliable detection of this error is
implementation dependent.
HP-UX 11i Version 1: September 2005 − 1 − Hewlett-Packard Company Section 2−−269