2004-11-03 13:51:07 +00:00
|
|
|
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
2007-06-20 22:33:04 +00:00
|
|
|
.TH "READV" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" readv
|
2007-09-20 06:03:25 +00:00
|
|
|
.SH PROLOG
|
|
|
|
This manual page is part of the POSIX Programmer's Manual.
|
|
|
|
The Linux implementation of this interface may differ (consult
|
|
|
|
the corresponding Linux manual page for details of Linux behavior),
|
|
|
|
or the interface may not be implemented on Linux.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
|
|
|
readv \- read a vector
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.LP
|
|
|
|
\fB#include <sys/uio.h>
|
|
|
|
.br
|
|
|
|
.sp
|
|
|
|
ssize_t readv(int\fP \fIfildes\fP\fB, const struct iovec *\fP\fIiov\fP\fB,
|
|
|
|
int\fP \fIiovcnt\fP\fB); \fP
|
|
|
|
\fB
|
|
|
|
.br
|
|
|
|
\fP
|
|
|
|
.SH DESCRIPTION
|
|
|
|
.LP
|
|
|
|
The \fIreadv\fP() function shall be equivalent to \fIread\fP(), except
|
|
|
|
as described
|
|
|
|
below. The \fIreadv\fP() function shall place the input data into
|
|
|
|
the \fIiovcnt\fP buffers specified by the members of the
|
|
|
|
\fIiov\fP array: \fIiov\fP[0], \fIiov\fP[1], ..., \fIiov\fP[ \fIiovcnt\fP-1].
|
|
|
|
The \fIiovcnt\fP argument is valid if greater
|
|
|
|
than 0 and less than or equal to {IOV_MAX}.
|
|
|
|
.LP
|
|
|
|
Each \fIiovec\fP entry specifies the base address and length of an
|
|
|
|
area in memory where data should be placed. The
|
|
|
|
\fIreadv\fP() function shall always fill an area completely before
|
|
|
|
proceeding to the next.
|
|
|
|
.LP
|
|
|
|
Upon successful completion, \fIreadv\fP() shall mark for update the
|
|
|
|
\fIst_atime\fP field of the file.
|
|
|
|
.SH RETURN VALUE
|
|
|
|
.LP
|
2007-11-18 06:25:23 +00:00
|
|
|
Refer to \fIread\fP().
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH ERRORS
|
|
|
|
.LP
|
2007-11-18 06:25:23 +00:00
|
|
|
Refer to \fIread\fP().
|
2004-11-03 13:51:07 +00:00
|
|
|
.LP
|
|
|
|
In addition, the \fIreadv\fP() function shall fail if:
|
|
|
|
.TP 7
|
|
|
|
.B EINVAL
|
|
|
|
The sum of the \fIiov_len\fP values in the \fIiov\fP array overflowed
|
|
|
|
an \fBssize_t\fP.
|
|
|
|
.sp
|
|
|
|
.LP
|
|
|
|
The \fIreadv\fP() function may fail if:
|
|
|
|
.TP 7
|
|
|
|
.B EINVAL
|
|
|
|
The \fIiovcnt\fP argument was less than or equal to 0, or greater
|
|
|
|
than {IOV_MAX}.
|
|
|
|
.sp
|
|
|
|
.LP
|
|
|
|
\fIThe following sections are informative.\fP
|
|
|
|
.SH EXAMPLES
|
|
|
|
.SS Reading Data into an Array
|
|
|
|
.LP
|
|
|
|
The following example reads data from the file associated with the
|
|
|
|
file descriptor \fIfd\fP into the buffers specified by
|
|
|
|
members of the \fIiov\fP array.
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fB#include <sys/types.h>
|
|
|
|
#include <sys/uio.h>
|
|
|
|
#include <unistd.h>
|
|
|
|
\&...
|
|
|
|
ssize_t bytes_read;
|
|
|
|
int fd;
|
|
|
|
char buf0[20];
|
|
|
|
char buf1[30];
|
|
|
|
char buf2[40];
|
|
|
|
int iovcnt;
|
|
|
|
struct iovec iov[3];
|
|
|
|
.sp
|
|
|
|
|
|
|
|
iov[0].iov_base = buf0;
|
|
|
|
iov[0].iov_len = sizeof(buf0);
|
|
|
|
iov[1].iov_base = buf1;
|
|
|
|
iov[1].iov_len = sizeof(buf1);
|
|
|
|
iov[2].iov_base = buf2;
|
|
|
|
iov[2].iov_len = sizeof(buf2);
|
|
|
|
\&...
|
|
|
|
iovcnt = sizeof(iov) / sizeof(struct iovec);
|
|
|
|
.sp
|
|
|
|
|
|
|
|
bytes_read = readv(fd, iov, iovcnt);
|
|
|
|
\&...
|
|
|
|
\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.SH APPLICATION USAGE
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH RATIONALE
|
|
|
|
.LP
|
2007-11-18 06:25:23 +00:00
|
|
|
Refer to \fIread\fP().
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH FUTURE DIRECTIONS
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH SEE ALSO
|
|
|
|
.LP
|
2007-09-20 06:11:55 +00:00
|
|
|
\fIread\fP(), \fIwritev\fP(), the Base Definitions volume of
|
2004-11-03 13:51:07 +00:00
|
|
|
IEEE\ Std\ 1003.1-2001, \fI<sys/uio.h>\fP
|
|
|
|
.SH COPYRIGHT
|
|
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
|
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
|
|
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
|
|
|
event of any discrepancy between this version and the original IEEE and
|
|
|
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
|
|
is the referee document. The original Standard can be obtained online at
|
|
|
|
http://www.opengroup.org/unix/online.html .
|