Reads from a file.
Standard C Library (libc.a)
#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);
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.
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.
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.
| 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:
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;
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:
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. |
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.2 General Programming Concepts: Writing and Debugging Programs.