diff options
Diffstat (limited to 'man3p/writev.3p')
| -rw-r--r-- | man3p/writev.3p | 124 |
1 files changed, 124 insertions, 0 deletions
diff --git a/man3p/writev.3p b/man3p/writev.3p new file mode 100644 index 000000000..aba53f254 --- /dev/null +++ b/man3p/writev.3p @@ -0,0 +1,124 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "WRITEV" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" writev +.SH NAME +writev \- write a vector +.SH SYNOPSIS +.LP +\fB#include <sys/uio.h> +.br +.sp +ssize_t writev(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 \fIwritev\fP() function shall be equivalent to \fIwrite\fP(), +except as described +below. The \fIwritev\fP() function shall gather output data from 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}, as defined in \fI<limits.h>\fP. +.LP +Each \fIiovec\fP entry specifies the base address and length of an +area in memory from which data should be written. The +\fIwritev\fP() function shall always write a complete area before +proceeding to the next. +.LP +If \fIfildes\fP refers to a regular file and all of the \fIiov_len\fP +members in the array pointed to by \fIiov\fP are 0, +\fIwritev\fP() shall return 0 and have no other effect. For other +file types, the behavior is unspecified. +.LP +If the sum of the \fIiov_len\fP values is greater than {SSIZE_MAX}, +the operation shall fail and no data shall be +transferred. +.SH RETURN VALUE +.LP +Upon successful completion, \fIwritev\fP() shall return the number +of bytes actually written. Otherwise, it shall return a +value of -1, the file-pointer shall remain unchanged, and \fIerrno\fP +shall be set to indicate an error. +.SH ERRORS +.LP +Refer to \fIwrite\fP() . +.LP +In addition, the \fIwritev\fP() function shall fail if: +.TP 7 +.B EINVAL +The sum of the \fIiov_len\fP values in the \fIiov\fP array would overflow +an \fBssize_t\fP. +.sp +.LP +The \fIwritev\fP() function may fail and set \fIerrno\fP to: +.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 Writing Data from an Array +.LP +The following example writes data from the buffers specified by members +of the \fIiov\fP array to the file associated with the +file descriptor \fIfd\fP. +.sp +.RS +.nf + +\fB#include <sys/types.h> +#include <sys/uio.h> +#include <unistd.h> +\&... +ssize_t bytes_written; +int fd; +char *buf0 = "short string\\n"; +char *buf1 = "This is a longer string\\n"; +char *buf2 = "This is the longest string in this example\\n"; +int iovcnt; +struct iovec iov[3]; +.sp + +iov[0].iov_base = buf0; +iov[0].iov_len = strlen(buf0); +iov[1].iov_base = buf1; +iov[1].iov_len = strlen(buf1); +iov[2].iov_base = buf2; +iov[2].iov_len = strlen(buf2); +\&... +iovcnt = sizeof(iov) / sizeof(struct iovec); +.sp + +bytes_written = writev(fd, iov, iovcnt); +\&... +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +Refer to \fIwrite\fP() . +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIreadv\fP() , \fIwrite\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI<limits.h>\fP, \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 . |