logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

writev.3p (4068B)

    

  1. '\" et
  2. .TH WRITEV "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. writev
  12. \(em write a vector
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <sys/uio.h>
  17. .P
  18. ssize_t writev(int \fIfildes\fP, const struct iovec *\fIiov\fP, int \fIiovcnt\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fIwritev\fR()
  23. function shall be equivalent to
  24. \fIwrite\fR(),
  25. except as described below. The
  26. \fIwritev\fR()
  27. function shall gather output data from the
  28. .IR iovcnt
  29. buffers specified by the members of the
  30. .IR iov
  31. array:
  32. .IR iov [0],
  33. .IR iov [1],
  34. \&.\|.\|., \fIiov\fR[\fIiovcnt\fR\-1].
  35. The
  36. .IR iovcnt
  37. argument is valid if greater than 0 and less than or equal to
  38. {IOV_MAX},
  39. as defined in
  40. .IR <limits.h> .
  41. .P
  42. Each
  43. .IR iovec
  44. entry specifies the base address and length of an area in memory from
  45. which data should be written. The
  46. \fIwritev\fR()
  47. function shall always write a complete area before proceeding to the
  48. next.
  49. .P
  50. If
  51. .IR fildes
  52. refers to a regular file and all of the
  53. .IR iov_len
  54. members in the array pointed to by
  55. .IR iov
  56. are 0,
  57. \fIwritev\fR()
  58. shall return 0 and have no other effect. For other file types, the
  59. behavior is unspecified.
  60. .P
  61. If the sum of the
  62. .IR iov_len
  63. values is greater than
  64. {SSIZE_MAX},
  65. the operation shall fail and no data shall be transferred.
  66. .SH "RETURN VALUE"
  67. Upon successful completion,
  68. \fIwritev\fR()
  69. shall return the number of bytes actually written. Otherwise, it shall
  70. return a value of \-1, the file-pointer shall remain unchanged, and
  71. .IR errno
  72. shall be set to indicate an error.
  73. .SH ERRORS
  74. Refer to
  75. .IR "\fIwrite\fR\^(\|)".
  76. .P
  77. In addition, the
  78. \fIwritev\fR()
  79. function shall fail if:
  80. .TP
  81. .BR EINVAL
  82. The sum of the
  83. .IR iov_len
  84. values in the
  85. .IR iov
  86. array would overflow an
  87. .BR ssize_t .
  88. .P
  89. The
  90. \fIwritev\fR()
  91. function may fail and set
  92. .IR errno
  93. to:
  94. .TP
  95. .BR EINVAL
  96. The
  97. .IR iovcnt
  98. argument was less than or equal to 0, or greater than
  99. {IOV_MAX}.
  100. .LP
  101. .IR "The following sections are informative."
  102. .SH EXAMPLES
  103. .SS "Writing Data from an Array"
  104. .P
  105. The following example writes data from the buffers specified by members
  106. of the
  107. .IR iov
  108. array to the file associated with the file descriptor
  109. .IR fd .
  110. .sp
  111. .RS 4
  112. .nf
  114. #include <sys/types.h>
  115. #include <sys/uio.h>
  116. #include <unistd.h>
  117. \&...
  118. ssize_t bytes_written;
  119. int fd;
  120. char *buf0 = "short string\en";
  121. char *buf1 = "This is a longer string\en";
  122. char *buf2 = "This is the longest string in this example\en";
  123. int iovcnt;
  124. struct iovec iov[3];
  125. .P
  126. iov[0].iov_base = buf0;
  127. iov[0].iov_len = strlen(buf0);
  128. iov[1].iov_base = buf1;
  129. iov[1].iov_len = strlen(buf1);
  130. iov[2].iov_base = buf2;
  131. iov[2].iov_len = strlen(buf2);
  132. \&...
  133. iovcnt = sizeof(iov) / sizeof(struct iovec);
  134. .P
  135. bytes_written = writev(fd, iov, iovcnt);
  136. \&...
  137. .fi
  138. .P
  139. .RE
  140. .SH "APPLICATION USAGE"
  141. None.
  142. .SH RATIONALE
  143. Refer to
  144. .IR "\fIwrite\fR\^(\|)".
  145. .SH "FUTURE DIRECTIONS"
  146. None.
  147. .SH "SEE ALSO"
  148. .IR "\fIreadv\fR\^(\|)",
  149. .IR "\fIwrite\fR\^(\|)"
  150. .P
  151. The Base Definitions volume of POSIX.1\(hy2017,
  152. .IR "\fB<limits.h>\fP",
  153. .IR "\fB<sys_uio.h>\fP"
  154. .\"
  155. .SH COPYRIGHT
  156. Portions of this text are reprinted and reproduced in electronic form
  157. from IEEE Std 1003.1-2017, Standard for Information Technology
  158. -- Portable Operating System Interface (POSIX), The Open Group Base
  159. Specifications Issue 7, 2018 Edition,
  160. Copyright (C) 2018 by the Institute of
  161. Electrical and Electronics Engineers, Inc and The Open Group.
  162. In the event of any discrepancy between this version and the original IEEE and
  163. The Open Group Standard, the original IEEE and The Open Group Standard
  164. is the referee document. The original Standard can be obtained online at
  165. http://www.opengroup.org/unix/online.html .
  166. .PP
  167. Any typographical or formatting errors that appear
  168. in this page are most likely
  169. to have been introduced during the conversion of the source files to
  170. man page format. To report such errors, see
  171. https://www.kernel.org/doc/man-pages/reporting_bugs.html .