read, readx, readv, readvx, or pread Subroutine

AIX Version 4.3 Base Operating System and Extensions Technical Reference, Volume 2

read, readx, readv, or readvx Subroutine

Purpose

Reads from a file.

Library

Standard C Library (libc.a)

Syntax

#include <unistd.h>

ssize_t read (FileDescriptor,
 Buffer, NBytes)
int FileDescriptor;
void *Buffer;
size_t NBytes;

int readx (FileDescriptor, ;Buffer, NBytes, Extension)
int FileDescriptor;
char * Buffer;
unsigned int NBytes;
int Extension;

#include <sys/uio.h>

ssize_t readv (FileDescriptor, iov, iovCount)
int FileDescriptor;
const struct iovec *iov;
int iovCount;

int readvx (FileDescriptor, iov, iovCount, Extension)
int FileDescriptor;
struct iovec *iov;
int iovCount;
int Extension;

#include <unistd.h>

ssize_t pread (int fildes, void *buf, size_t nbyte, off_t offset);

Description

The read subroutine attempts to read NBytes of data from the file associated with the FileDescriptor parameter into the buffer pointed to by the Buffer parameter.

The readv subroutine performs the same action but scatters the input data into the iovCount buffers specified by the array of iovec structures pointed to by the iov parameter. Each iovec entry specifies the base address and length of an area in memory where data should be placed. The readv subroutine always fills an area completely before proceeding to the next.

The readx and readvx subroutines are the same as the read and readv subroutines, respectively, with the addition of an Extension parameter, which is needed when reading from some device drivers and when reading directories. While directories can be read directly, it is recommended that the opendir and readdir calls be used instead, as this is a more portable interface.

On regular files and devices capable of seeking, the read starts at a position in the file given by the file pointer associated with the FileDescriptor parameter. Upon return from the read subroutine, 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 file is undefined.

On directories, the readvx subroutine starts at the position specified by the file pointer associated with the FileDescriptor parameter. The value of this file pointer must be either 0 or a value which the file pointer had immediately after a previous call to the readvx subroutine on this directory. Upon return from the readvx subroutine, the file pointer increments by a number that may not correspond to the number of bytes copied into the buffers.

When attempting to read from an empty pipe (first-in-first-out (FIFO)):

If no process has the pipe open for writing, the read returns 0 to indicate end-of-file.
If some process has the pipe open for writing:
- If O_NDELAY and O_NONBLOCK are clear (the default), the read blocks until some data is written or the pipe is closed by all processes that had opened the pipe for writing.
- If O_NDELAY is set, the read subroutine returns a value of 0.
- If O_NONBLOCK is set, the read subroutine returns a value of -1 and sets the global variable errno to EAGAIN.

When attempting to read from a character special file that supports nonblocking reads, such as a terminal, and no data is currently available:

If O_NDELAY and O_NONBLOCK are clear (the default), the read subroutine blocks until data becomes available.
If O_NDELAY is set, the read subroutine returns 0.
If O_NONBLOCK is set, the read subroutine returns -1 and sets the errno global variable to EAGAIN if no data is available.

When attempting to read a regular file that supports enforcement mode record locks, and all or part of the region to be read is currently locked by another process:

If O_NDELAY and O_NONBLOCK are clear, the read blocks the calling process until the lock is released.
If O_NDELAY or O_NONBLOCK is set, the read returns -1 and sets the global variable errno to EAGAIN.

The behavior of an interrupted read subroutine depends on how the handler for the arriving signal was installed.

Note: A read from a regular file is not interruptible. Only reads from objects that may block indefinitely, such as FIFOs, sockets, and some devices, are generally interruptible.

If the handler was installed with an indication that subroutines should not be restarted, the read subroutine returns a value of -1 and the global variable errno is set to EINTR (even if some data was already consumed).

If the handler was installed with an indication that subroutines should be restarted:

If no data had been read when the interrupt was handled, this read will not return a value (it is restarted).
If data had been read when the interrupt was handled, this read subroutine returns the amount of data consumed.

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 to 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.

Parameters

FileDescriptor

A file descriptor identifying the object to be read.

Extension

Provides communication with character device drivers that require additional information or return additional status. Each driver interprets the Extension parameter in a device-dependent way, either as a value or as a pointer to a communication area. Drivers must apply reasonable defaults when the value of the Extension parameter is 0.

For directories, the Extension parameter determines the format in which directory entries should be returned:

If the value of the Extension parameter is 0, the format in which directory entries are returned depends on the value of the real directory read flag (described in the ulimit subroutine).
If the calling process does not have the real directory read flag set, the buffers are filled with an array of directory entries truncated to fit the format of the System V directory structure. This provides compatibility with programs written for UNIX System V.
If the calling process has the real directory read flag set (see the ulimit subroutine), the buffers are filled with an image of the underlying implementation of the directory.
If the value of the Extension parameter is 1, the buffers are filled with consecutive directory entries in the format of a dirent structure. This is logically equivalent to the readdir subroutine.
Other values of the Extension parameter are reserved.

For tape devices, the Extension parameter determines the response of the readx subroutine when the tape drive is in variable block mode and the read request is for less than the tape's block size.

If the value of the Extension parameter is TAPE_SHORT_READ, the readx subroutine returns the number of bytes requested and sets the errno global variable to a value of 0.
If the value of the Extension parameter is 0, the readx subroutine returns a value of 0 and sets the errno global variable to ENOMEM.

iov

Points to an array of iovec structures that identifies the buffers into which the data is to be placed. The iovec structure is defined in the sys/uio.h file and contains the following members:

caddr_t iov_base;
size_t iov_len;

iovCount	Specifies the number of iovec structures pointed to by the iov parameter.
Buffer	Points to the buffer.
NBytes	Specifies the number of bytes read from the file associated with the FileDescriptor parameter. Note: When reading tapes, the read subroutines consume a physical tape block on each call to the subroutine. If the physical data block size is larger than specified by the Nbytes parameter, an error will be returned, since all of the data from the read will not fit into the buffer specified by the read. To avoid read errors due to unknown blocking sizes on tapes, set the NBytes parameter to a very large value (such as 32K bytes).

Return Values

Upon successful completion, the read, readx, readv, readvx, and pread subroutines return the number of bytes actually read and placed into buffers. The system guarantees to read the number of bytes requested if the descriptor references a normal file that has the same number of bytes left before the end of the file is reached, but in no other case.

A value of 0 is returned when the end of the file has been reached. (For information about communication files, see the ioctl and termio files.)

Otherwise, a value of -1 is returned, the global variable errno is set to identify the error, and the content of the buffer pointed to by the Buffer or iov parameter is indeterminate.

Error Codes

The read, readx, readv, readvx, and pread subroutines are unsuccessful if one or more of the following are true:

EBADMSG	The file is a STREAM file that is set to control-normal mode and the message waiting to be read includes a control part.
EBADF	The FileDescriptor parameter is not a valid file descriptor open for reading.
EINVAL	The file position pointer associated with the FileDescriptor parameter was negative.
EINVAL	The sum of the iov_len values in the iov array was negative or overflowed a 32-bit integer.
EINVAL	The value of the iovCount parameter was not between 1 and 16, inclusive.

EINVAL	The STREAM or multiplexer referenced by FileDescriptor is linked (directly or indirectly) downstream from a multiplexer.
EAGAIN	The file was marked for non-blocking I/O, and no data was ready to be read.
EFAULT	The Buffer or part of the iov points to a location outside of the allocated address space of the process.
EDEADLK	A deadlock would occur if the calling process were to sleep until the region to be read was unlocked.
EINTR	A read was interrupted by a signal before any data arrived, and the signal handler was installed with an indication that subroutines are not to be restarted.
EIO	An I/O error occurred while reading from the file system.
EIO	The process is a member of a background process attempting to read from its controlling terminal, and either the process is ignoring or blocking the SIGTTIN signal or the process group has no parent process.

Note: The EOVERFLOW error code applies to Version 4.2 and later releases.

EOVERFLOW

An attempt was made to read from a regular file where NBytes was greater than zero and the starting offset was before the end-of-file and was greater than or equal to the offset maximum established in the open file description associated with FileDescriptor.

The read, readx, readv, readvx and pread subroutines may be unsuccessful if the following is true:

ENXIO	A request was made of a nonexistent device, or the request was outside the capabilities of the device.
ESPIPE	fildes is associated with a pipe or FIFO.

If Network File System (NFS) is installed on the system, the read system call can also fail if the following is true:

ETIMEDOUT

The connection timed out.

Implementation Specifics

These subroutines are part of Base Operating System (BOS) Runtime.

Related Information

The fcntl, dup, or dup2 subroutine, ioctl subroutine, lockfx subroutine, lseek subroutine, open, openx, or creat subroutine, opendir, readdir, or seekdir subroutine, pipe subroutine, poll subroutine, socket subroutine, socketpair subroutine.

The Input and Output Handling Programmer's Overview in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.