NAME | SYNOPSIS | FEATURES | DESCRIPTION | PARAMETERS | RETURN VALUES | ERRORS | ATTRIBUTES | SEE ALSO
#include <sys/types.h> #include <sys/uio.h> #include <unistd.h>ssize_t read(int d, void * buf, size_t nbytes);
MSDOSFS, NFS_CLIENT, UFS, POSIX_SOCKETS
read() attempts to read nbytes of data from the object referenced by the descriptor d into the buffer pointed to by buf . readv() performs the same action, but scatters the input data into the iovcnt buffers specified by the members of the iov array: iov[0] , iov[1] , ..., iov[iovcnt-1] .
On objects capable of seeking, read() starts at a position given by the pointer associated with d . See lseek(2POSIX) . Upon return from read() , the pointer is incremented by the number of bytes actually read.
Objects that are not capable of seeking always read from the current position. The value of the pointer associated with this type of object is undefined.
read() takes the following parameters:
Descriptor of the object from which to read. This is a file descriptor from an accept(2POSIX) , dup(2POSIX) , open(2POSIX) , shm_open(2POSIX) or socket(2POSIX) call.
Buffer into which data is read.
Number of bytes of data to read.
readv() takes the following parameters:
Descriptor of the object from which to read. This is a file descriptor from an accept(2POSIX) , dup(2POSIX) , open(2POSIX) , shm_open(2POSIX) or socket(2POSIX) call.
Array of buffers into which data is read.
Number of buffers into which data is read.
For
readv()
, the
iovec
structure is defined as:
struct iovec { char *iov_base; /* base address */ size_t iov_len; /* length */ };
Each
iovec
entry specifies the base address and length of an area in memory where data should be placed.
readv()
always fills an area completely before proceeding to the next one.
Upon successful completion, read() and readv() return the number of bytes actually read and placed in the buffer. The system guarantees to read the number of bytes requested if the descriptor references a normal file that contains that many bytes before the end-of-file, but in no other case. Upon end-of-file, 0 is returned. read() and readv() also return 0 if a non-blocking read is attempted on a socket that is no longer open. Otherwise, -1 is returned, and the global variable errno is set to indicate the error.
read() and readv() succeed unless:
The file was marked for non-blocking I/O , and no data were ready to be extracted..
d is not a valid file or socket descriptor open for reading.
In user mode, buf points outside the allocated address space. In supervisor mode, this is not detected and the target may behave unpredictably.
A read from a slow device was interrupted by the delivery of a signal before any data arrived.
The pointer associated with d was negative.
An I/O error occurred while reading from the file system.
In addition, readv() may return one of the following errors:
Part of iov points outside the allocated address space.
iovcnt was less than or equal to 0 , or greater than 16 .
One of the iov_len values in the iov array was negative.
The sum of the iov_len values in the iov array overflowed a 32-bit integer.
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
Interface Stability | Evolving |
dup(2POSIX) , fcntl(2POSIX) , open(2POSIX) , pipe(2POSIX) , select(2POSIX) , socket(2POSIX) , socketpair(2POSIX)
NAME | SYNOPSIS | FEATURES | DESCRIPTION | PARAMETERS | RETURN VALUES | ERRORS | ATTRIBUTES | SEE ALSO