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

readv.3p (3442B)

    

  1. '\" et
  2. .TH READV "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. readv
  12. \(em read a vector
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <sys/uio.h>
  17. .P
  18. ssize_t readv(int \fIfildes\fP, const struct iovec *\fIiov\fP, int \fIiovcnt\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fIreadv\fR()
  23. function shall be equivalent to
  24. \fIread\fR(),
  25. except as described below. The
  26. \fIreadv\fR()
  27. function shall place the input data into 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. \&.\|.\|.,
  35. .IR iov [\c
  36. .IR iovcnt \-1].
  37. The
  38. .IR iovcnt
  39. argument is valid if greater than 0 and less than or equal to
  40. {IOV_MAX}.
  41. .P
  42. Each
  43. .IR iovec
  44. entry specifies the base address and length of an area
  45. in memory where data should be placed. The
  46. \fIreadv\fR()
  47. function shall always fill an area completely before proceeding
  48. to the next.
  49. .P
  50. Upon successful completion,
  51. \fIreadv\fR()
  52. shall mark for update the last data access timestamp of the file.
  53. .SH "RETURN VALUE"
  54. Refer to
  55. .IR "\fIread\fR\^(\|)".
  56. .SH ERRORS
  57. Refer to
  58. .IR "\fIread\fR\^(\|)".
  59. .P
  60. In addition, the
  61. \fIreadv\fR()
  62. function shall fail if:
  63. .TP
  64. .BR EINVAL
  65. The sum of the
  66. .IR iov_len
  67. values in the
  68. .IR iov
  69. array overflowed an
  70. .BR ssize_t .
  71. .P
  72. The
  73. \fIreadv\fR()
  74. function may fail if:
  75. .TP
  76. .BR EINVAL
  77. The
  78. .IR iovcnt
  79. argument was less than or equal to 0, or greater than
  80. {IOV_MAX}.
  81. .LP
  82. .IR "The following sections are informative."
  83. .SH EXAMPLES
  84. .SS "Reading Data into an Array"
  85. .P
  86. The following example reads data from the file associated with the file
  87. descriptor
  88. .IR fd
  89. into the buffers specified by members of the
  90. .IR iov
  91. array.
  92. .sp
  93. .RS 4
  94. .nf
  96. #include <sys/types.h>
  97. #include <sys/uio.h>
  98. #include <unistd.h>
  99. \&...
  100. ssize_t bytes_read;
  101. int fd;
  102. char buf0[20];
  103. char buf1[30];
  104. char buf2[40];
  105. int iovcnt;
  106. struct iovec iov[3];
  107. .P
  108. iov[0].iov_base = buf0;
  109. iov[0].iov_len = sizeof(buf0);
  110. iov[1].iov_base = buf1;
  111. iov[1].iov_len = sizeof(buf1);
  112. iov[2].iov_base = buf2;
  113. iov[2].iov_len = sizeof(buf2);
  114. \&...
  115. iovcnt = sizeof(iov) / sizeof(struct iovec);
  116. .P
  117. bytes_read = readv(fd, iov, iovcnt);
  118. \&...
  119. .fi
  120. .P
  121. .RE
  122. .SH "APPLICATION USAGE"
  123. None.
  124. .SH RATIONALE
  125. Refer to
  126. .IR "\fIread\fR\^(\|)".
  127. .SH "FUTURE DIRECTIONS"
  128. None.
  129. .SH "SEE ALSO"
  130. .IR "\fIread\fR\^(\|)",
  131. .IR "\fIwritev\fR\^(\|)"
  132. .P
  133. The Base Definitions volume of POSIX.1\(hy2017,
  134. .IR "\fB<sys_uio.h>\fP"
  135. .\"
  136. .SH COPYRIGHT
  137. Portions of this text are reprinted and reproduced in electronic form
  138. from IEEE Std 1003.1-2017, Standard for Information Technology
  139. -- Portable Operating System Interface (POSIX), The Open Group Base
  140. Specifications Issue 7, 2018 Edition,
  141. Copyright (C) 2018 by the Institute of
  142. Electrical and Electronics Engineers, Inc and The Open Group.
  143. In the event of any discrepancy between this version and the original IEEE and
  144. The Open Group Standard, the original IEEE and The Open Group Standard
  145. is the referee document. The original Standard can be obtained online at
  146. http://www.opengroup.org/unix/online.html .
  147. .PP
  148. Any typographical or formatting errors that appear
  149. in this page are most likely
  150. to have been introduced during the conversion of the source files to
  151. man page format. To report such errors, see
  152. https://www.kernel.org/doc/man-pages/reporting_bugs.html .