read, readx, read64x, readv, readvx, eread, ereadv, pread, or preadv Subroutine

Purpose

Reads from a file.

Library

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;

int read64x (FileDescriptor, Buffer, NBytes, Extension)
int FileDescriptor;
void *Buffer;
size_t NBytes;
void *Extension;

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

#include <sys/uio.h>

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

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

#include <unistd.h>
#include <sys/uio.h>

ssize_t preadv ( 
int  FileDescriptor,
const struct iovec * iov,
int iovCount,
offset_t offset);

ssize_t eread (FileDescriptor, Buffer, Nbytes,  labels)
int FileDescriptor;
const void * Buffer;
size_t  NBytes;sec_labels_t * labels;

ssize_t ereadv (FileDescriptor, iov, iovCount, labels)
int FileDescriptor;
const struct iovec * iov;
int iovCount;
sec_labels_t * labels;

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)):

• 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 toEAGAIN.

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

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 read64x subroutine is the same as the readx subroutine, where the Extension parameter is a pointer to a j2_ext structure (see the j2/j2_cntl.h file). The read64x subroutine is used to read an encrypted file in raw mode (see O_RAW in the fcntl.h file). Using the O_RAW flag on encrypted files has the same limitations as using O_DIRECT on regular files.

The eread and ereadv subroutines read from the stream and retrieve the message. The eread subroutine copies the number of bytes of the data from the buffer to a stream associated with the FileDescriptor parameter. The Nbyte parameter specifies the number of bytes. The Buffer parameter points to the buffer. Security information is returned in the structure pointed to by the labels parameter.

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.

ssize_t pread64(int fildes , 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. If fildes refers to a socket, read is equivalent to the recv subroutine with no flags set.

Using the read or pread subroutine with a file descriptor obtained from a call to the shm_open subroutine fails with ENXIO.

The preadv subroutine performs the same action as the readv subroutine, except that the preadv subroutine reads from a given position in the file without changing the file pointer. The first three arguments of the preadv subroutine are the same as the readv subroutine with the addition of the offset argument that points to the position that you want inside the file. An error occurs when the file that the preadv subroutine reads from is incapable of seeking.

Parameters

caddr_t iov_base;
size_t iov_len;

Return Values

Upon successful completion, the read, readx, read64x, readv, readvx, pread, and preadv 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.

Upon successful completion, the eread and ereadv subroutines return a value of 0. Otherwise, the global variable errno is set to identify the error.

Error Codes

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

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

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