Reads from a file.
Standard C Library (libc.a)
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;
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;
ssize_t pread (int fildes, void *buf, size_t nbyte, off_t offset);
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)):
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.
|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:
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.
|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
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.
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.
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.|
These subroutines are part of Base Operating System (BOS) Runtime.
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.