read.2 (2010 09)

ManualsBrandsHP ManualsSoftwareHP-UX Manpages

read(2) read(2)

NAME

read, readv, pread - read from ﬁle

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 ﬁle associated with the open ﬁle descriptor,

ﬁldes, into the buffer pointed to by buf.

If nbyte is 0,

read() will return 0 and have no other results.

On ﬁles that support seeking (for example, a regular ﬁle), the

read() starts at a position in the ﬁle

given by the ﬁle offset associated with ﬁldes . The ﬁle offset is incremented by the number of bytes actu-

ally read.

Files that do not support seeking, for example, terminals, always read from the current position. The

value of a ﬁle offset associated with such a ﬁle is undeﬁned.

No data transfer will occur past the current end- of-ﬁle. If the starting position is at or after the

end-of-ﬁle, 0 will be returned. If the ﬁle refers to a device special ﬁle, 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, 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 ﬁle or the ﬁle is no longer open for writing.

When attempting to read a ﬁle (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 ﬂag has no effect if there is some data available.

When attempting to read from a regular ﬁle with enforcement-mode ﬁle and record locking set (see

chmod(2)), and the segment of the ﬁle to be read is blocked by a write lock owned by another process, the

behavior is determined by the

O_NDELAY and O_NONBLOCK ﬁle status ﬂags:

• 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 a ﬁle 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.

The

read() function reads data previously written to a ﬁle. If any portion of a regular ﬁle prior to the

end-of-ﬁle has not been written, read() returns bytes with value 0. For example, lseek() allows the

ﬁle offset to be set beyond the end of existing data in the ﬁle. 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.

HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1

Summary of content (4 pages)

PAGE 1
read(2) read(2) NAME read, readv, pread - read from file SYNOPSIS #include ssize_t read(int fildes, void *buf, size_t nbyte); ssize_t pread(int fildes, void *buf, size_t nbyte, off_t offset); #include 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.
PAGE 2
read(2) read(2) 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.
PAGE 3
read(2) read(2) Upon successful completion, readv() marks for update the st_atime field of the file. The pread() function performs the same action as read(), except that it reads from a given position in the file without changing the file pointer. The first three arguments of pread() are the same as read() with the addition of a fourth argument offset for the desired position inside the file. An attempt to perform a pread() on a file that is incapable of seeking results in an error.
PAGE 4
read(2) read(2) The readv() function may fail if: [EINVAL] The iovcnt argument was less than or equal to 0, or greater than {IOV_MAX}. The pread() function will fail and the file pointer remains unchanged if: [EINVAL] The offset argument is invalid. The value is negative. [EOVERFLOW] The file is a regular file and an attempt was made to read at or beyond the offset maximum associated with the file. [ESPIPE] fildes is associated with a pipe or FIFO.