[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]

Technical Reference: Base Operating System and Extensions , Volume 2


read, readx, readv, readvx, or pread Subroutine

Purpose

Reads from a file.

Library

Standard C Library (libc.a)

Syntax

#include <unistd.h>


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


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

#include <sys/uio.h>


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

int readvx (FileDescriptorioviovCountExtension)
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 theFileDescriptor 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)):

When attempting to read from a character special file that supports nonblocking reads, such as a terminal, and no data is currently 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:

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:

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.

Note: The pread64 subroutine applies to AIX 4.3 and later.

ssize_t pread64(int filedes , void *buf , size_t nbytes , off64_t offset)

The pread64 subroutines performs the same action as pread but the limit of offset to the maximum file size for the file associated with the file Descriptor and DEV_OFF_MAX if the file associated with fileDescriptor is a block special or character special file.

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 theExtension 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 (ulimit Subroutine) 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 adirent 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 theFileDescriptor 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 AIX 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 in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.


[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]