READ(2)

NAME

read, readv − read input

SYNOPSIS

int read (fildes, buf, nbyte)
int fildes;
char ∗buf;
unsigned nbyte; #include <sys/types.h>
#include <sys/uio.h>
int readv (fildes, iov, iovcnt)
int fildes;
struct iovec *iov;
int iovcnt;

HP-UX COMPATIBILITY

Level: read: HP-UX/RUN ONLY

readv: HP-UX/STANDARD

Origin: System V, UCB, and HP

DESCRIPTION

Fildes is a file descriptor obtained from a creat, open, dup, fcntl, or pipe system call.

Read attempts to read nbyte bytes from the file associated with fildes into the buffer pointed to by buf. Readv performs the same action but scatters the input data into the iovcnt buffers specified by the elements of the iovec array: iov[0], iov[1], ..., iov[ iovcnt - 1].

For readv the iovec structure is defined as

struct iovec {
caddr_tiov_base;
intiov_len;
};

Each iovec entry specifies the base address and length of an area in memory where data should be placed. Readv will always fill one area completely before proceeding to the next area. The iovec array may be at most MAXIOV long.

On devices capable of seeking, the read starts at a position in the file given by the file pointer associated with fildes. Upon return from read, the file pointer is incremented by the number of bytes actually read.

Devices that are incapable of seeking always read from the current position. The value of a file pointer associated with such a device is undefined.

Upon successful completion, read returns the number of bytes actually read and placed in the buffer; this number may be less than nbyte if 1) the file is associated with a communication line (see ioctl(2) and termio(4)), or 2) if the number of bytes left in the file is less than nbyte bytes. A value of 0 is returned when an end-of-file has been reached.

When attempting to read from an empty pipe (or FIFO):

If O_NDELAY is set, the read will return a 0.

If O_NDELAY is clear, the read will block 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 will return a 0.

If O_NDELAY is clear, the read will block until data becomes available.

ERRORS

Read will fail if one of the following conditions is true and errno will be set accordingly:

[EBADF] Fildes is not a valid file descriptor open for reading.

[EFAULT] Buf points outside the allocated address space.

[EINTR] A signal was caught during the read system call.

[EDEADLK] A resource deadlock would occur as a result of this operation (see lockf(2)).

In addition, readv may return one of the following errors:

[EINVAL] Iovcnt was less than or equal to 0, or greater then MAXIOV.

[EINVAL] One of the iov len values in the iov array was negative.

[EINVAL] The sum of iov len values in the iov array overflowed a 32-bit integer.

RETURN VALUE

Upon successful completion a non-negative integer is returned indicating the number of bytes actually read. Otherwise, a −1 is returned and errno is set to indicate the error.

CAVEATS

Record locking may or may not be enforced by the system depending on the setting of the file’s mode bits (see lockf(2)).

BUGS

The character special devices, and raw discs in particular, apply constraints on how read can be used. See the specific Section 4 entries for details on particular devices.

HARDWARE DEPENDENCIES

Series 500:
Readv is not currently supported on the Series 500.

Integral PC:
Information read from a disc by the operating system is cached in memory to speed up access to information in files. Consequently, not every read operation causes the system to access the physical medium. If it becomes necessary to access the physical medium, you should execute sync before executing read.

Museum

Related Articles