mirror of https://github.com/mkerrisk/man-pages
125 lines
3.6 KiB
Plaintext
125 lines
3.6 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "WRITEV" 3P 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 .
|