diff options
Diffstat (limited to 'man3p/readv.3p')
| -rw-r--r-- | man3p/readv.3p | 115 |
1 files changed, 115 insertions, 0 deletions
diff --git a/man3p/readv.3p b/man3p/readv.3p new file mode 100644 index 000000000..1830265f1 --- /dev/null +++ b/man3p/readv.3p @@ -0,0 +1,115 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "READV" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" readv +.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 +Refer to \fIread\fP() . +.SH ERRORS +.LP +Refer to \fIread\fP() . +.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 +Refer to \fIread\fP() . +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIread\fP() , \fIwritev\fP() , the Base Definitions volume of +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 . |