READ(2) — HP-UX

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;

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_t	iov_base;
	unsigned iov_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(7)), 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 ordinary file with enforcement-mode file and record locking set (see chmod(2)), and the segment of the file to be read has a blocking write lock (i.e., a write lock owned by another process):

If O_NDELAY is set, the function read will return −1 and errno will be set to EAGAIN.

If O_NDELAY is clear, the function read will sleep until the blocking write lock is removed.

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.

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.

EXAMPLES

Assuming a process opened a file for reading, the following call to read(2) reads BUFSIZ bytes from the file into the buffer pointed to by mybuf:

#include <stdio.h> /*include this for BUFSIZ definition*/ char mybuf[BUFSIZ];
int nbytes;

nbytes = read (myfd, mybuf, BUFSIZ);

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.

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

[EAGAIN] Enforcement-mode file and record locking was set, O_NDELAY was set, and there was 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. The reliable detection of this error will be implementation-dependent.

[ENOLCK] The system record lock table was full, so the read could not go to sleep until the blocking write lock was removed.

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

[EFAULT] Iov_base or iov points outside of the allocated address space. The reliable detection of this error will be implementation dependent.

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

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

[EISDIR] An attempt was made to read a directory on an NFS file system using the read system call.

WARNINGS

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

The character-special devices, and raw disks in particular, apply constraints on how read can be used. See the specific Section (7) entries for details on particular devices.

Check all references to signal(2) for appropriateness on systems that support sigvector(2). Sigvector(2) can affect the behavior described on this page.

In general, avoid using read to get the contents of a directory; use the readdir library routine, see directory(3C).

DEPENDENCIES

NFS When obtaining the contents of a directory on an NFS file system, the readdir library routine must be used, see directory(3C). Read will return with an error if used to read a directory using NFS.

AUTHOR

Read was developed by HP, AT&T, and the University of California, Berkeley.

Museum

Related Articles