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

lio_listio.3p (10488B)


  1. '\" et
  2. .TH LIO_LISTIO "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. lio_listio
  12. \(em list directed I/O
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <aio.h>
  17. .P
  18. int lio_listio(int \fImode\fP, struct aiocb *restrict const \fIlist\fP[restrict],
  19. int \fInent\fP, struct sigevent *restrict \fIsig\fP);
  20. .fi
  21. .SH DESCRIPTION
  22. The
  23. \fIlio_listio\fR()
  24. function shall initiate a list of I/O requests with a single
  25. function call.
  26. .P
  27. The
  28. .IR mode
  29. argument takes one of the values LIO_WAIT or LIO_NOWAIT declared in
  30. .IR <aio.h>
  31. and determines whether the function returns when the I/O operations
  32. have been completed, or as soon as the operations have been queued. If
  33. the
  34. .IR mode
  35. argument is LIO_WAIT, the function shall wait until all I/O is
  36. complete and the
  37. .IR sig
  38. argument shall be ignored.
  39. .P
  40. If the
  41. .IR mode
  42. argument is LIO_NOWAIT, the function shall return immediately, and
  43. asynchronous notification shall occur, according to the
  44. .IR sig
  45. argument, when all the I/O operations complete. If
  46. .IR sig
  47. is NULL, then no asynchronous notification shall occur. If
  48. .IR sig
  49. is not NULL, asynchronous notification occurs as specified in
  50. .IR "Section 2.4.1" ", " "Signal Generation and Delivery"
  51. when all the requests in
  52. .IR list
  53. have completed.
  54. .P
  55. The I/O requests enumerated by
  56. .IR list
  57. are submitted in an unspecified order.
  58. .P
  59. The
  60. .IR list
  61. argument is an array of pointers to
  62. .BR aiocb
  63. structures. The array contains
  64. .IR nent
  65. elements. The array may contain NULL elements, which shall be ignored.
  66. .P
  67. If the buffer pointed to by
  68. .IR list
  69. or the
  70. .BR aiocb
  71. structures pointed to by the elements of the array
  72. .IR list
  73. become illegal addresses before all asynchronous I/O completed and, if
  74. necessary, the notification is sent, then the behavior is undefined. If
  75. the buffers pointed to by the
  76. .IR aio_buf
  77. member of the
  78. .BR aiocb
  79. structure pointed to by the elements of the array
  80. .IR list
  81. become illegal addresses prior to the asynchronous I/O associated with
  82. that
  83. .BR aiocb
  84. structure being completed, the behavior is undefined.
  85. .P
  86. The
  87. .IR aio_lio_opcode
  88. field of each
  89. .BR aiocb
  90. structure specifies the operation to be performed. The supported
  91. operations are LIO_READ, LIO_WRITE, and LIO_NOP;
  92. these symbols are defined in
  93. .IR <aio.h> .
  94. The LIO_NOP operation causes the list entry to be ignored. If the
  95. .IR aio_lio_opcode
  96. element is equal to LIO_READ, then an I/O operation is submitted as if
  97. by a call to
  98. \fIaio_read\fR()
  99. with the
  100. .IR aiocbp
  101. equal to the address of the
  102. .BR aiocb
  103. structure. If the
  104. .IR aio_lio_opcode
  105. element is equal to LIO_WRITE, then an I/O operation is submitted as if
  106. by a call to
  107. \fIaio_write\fR()
  108. with the
  109. .IR aiocbp
  110. equal to the address of the
  111. .BR aiocb
  112. structure.
  113. .P
  114. The
  115. .IR aio_fildes
  116. member specifies the file descriptor on which the operation is to be
  117. performed.
  118. .P
  119. The
  120. .IR aio_buf
  121. member specifies the address of the buffer to or from which the data is
  122. transferred.
  123. .P
  124. The
  125. .IR aio_nbytes
  126. member specifies the number of bytes of data to be transferred.
  127. .P
  128. The members of the
  129. .BR aiocb
  130. structure further describe the I/O operation to be performed, in a
  131. manner identical to that of the corresponding
  132. .BR aiocb
  133. structure when used by the
  134. \fIaio_read\fR()
  135. and
  136. \fIaio_write\fR()
  137. functions.
  138. .P
  139. The
  140. .IR nent
  141. argument specifies how many elements are members of the list; that is,
  142. the length of the array.
  143. .P
  144. The behavior of this function is altered according to the definitions
  145. of synchronized I/O data integrity completion and synchronized I/O file
  146. integrity completion if synchronized I/O is enabled on the file
  147. associated with
  148. .IR aio_fildes .
  149. .P
  150. For regular files, no data transfer shall occur past the offset maximum
  151. established in the open file description associated with
  152. \fIaiocbp\fR\->\fIaio_fildes\fR.
  153. .P
  154. If \fIsig\fR\->\fIsigev_notify\fR is SIGEV_THREAD and
  155. \fIsig\fR\->\fIsigev_notify_attributes\fR is a non-null pointer and the
  156. block pointed to by this pointer becomes an illegal address prior to
  157. all asynchronous I/O being completed, then the behavior is undefined.
  158. .SH "RETURN VALUE"
  159. If the
  160. .IR mode
  161. argument has the value LIO_NOWAIT, the
  162. \fIlio_listio\fR()
  163. function shall return the value zero if the I/O operations are
  164. successfully queued; otherwise, the function shall return the value
  165. \-1 and set
  166. .IR errno
  167. to indicate the error.
  168. .P
  169. If the
  170. .IR mode
  171. argument has the value LIO_WAIT, the
  172. \fIlio_listio\fR()
  173. function shall return the value zero when all the indicated I/O has
  174. completed successfully. Otherwise,
  175. \fIlio_listio\fR()
  176. shall return a value of \-1 and set
  177. .IR errno
  178. to indicate the error.
  179. .P
  180. In either case, the return value only indicates the success or failure
  181. of the
  182. \fIlio_listio\fR()
  183. call itself, not the status of the individual I/O requests. In some
  184. cases one or more of the I/O requests contained in the list may fail.
  185. Failure of an individual request does not prevent completion of any
  186. other individual request. To determine the outcome of each I/O
  187. request, the application shall examine the error status associated with
  188. each
  189. .BR aiocb
  190. control block. The error statuses so returned are identical to those
  191. returned as the result of an
  192. \fIaio_read\fR()
  193. or
  194. \fIaio_write\fR()
  195. function.
  196. .SH ERRORS
  197. The
  198. \fIlio_listio\fR()
  199. function shall fail if:
  200. .TP
  201. .BR EAGAIN
  202. The resources necessary to queue all the I/O requests were not
  203. available. The application may check the error status for each
  204. .BR aiocb
  205. to determine the individual request(s) that failed.
  206. .TP
  207. .BR EAGAIN
  208. The number of entries indicated by
  209. .IR nent
  210. would cause the system-wide limit
  211. {AIO_MAX}
  212. to be exceeded.
  213. .TP
  214. .BR EINVAL
  215. The
  216. .IR mode
  217. argument is not a proper value, or the value of
  218. .IR nent
  219. was greater than
  220. {AIO_LISTIO_MAX}.
  221. .TP
  222. .BR EINTR
  223. A signal was delivered while waiting for all I/O requests to complete
  224. during an LIO_WAIT operation. Note that, since each I/O operation
  225. invoked by
  226. \fIlio_listio\fR()
  227. may possibly provoke a signal when it completes, this error return may
  228. be caused by the completion of one (or more) of the very I/O operations
  229. being awaited. Outstanding I/O requests are not canceled, and the
  230. application shall examine each list element to determine whether the
  231. request was initiated, canceled, or completed.
  232. .TP
  233. .BR EIO
  234. One or more of the individual I/O operations failed. The application
  235. may check the error status for each
  236. .BR aiocb
  237. structure to determine the individual request(s) that failed.
  238. .P
  239. In addition to the errors returned by the
  240. \fIlio_listio\fR()
  241. function, if the
  242. \fIlio_listio\fR()
  243. function succeeds or fails with errors of
  244. .BR [EAGAIN] ,
  245. .BR [EINTR] ,
  246. or
  247. .BR [EIO] ,
  248. then some of the I/O specified by the list may have been initiated. If
  249. the
  250. \fIlio_listio\fR()
  251. function fails with an error code other than
  252. .BR [EAGAIN] ,
  253. .BR [EINTR] ,
  254. or
  255. .BR [EIO] ,
  256. no operations from the list shall have been initiated. The I/O operation
  257. indicated by each list element can encounter errors specific to the
  258. individual read or write function being performed. In this event, the
  259. error status for each
  260. .BR aiocb
  261. control block contains the associated error code. The error codes that
  262. can be set are the same as would be set by a
  263. \fIread\fR()
  264. or
  265. \fIwrite\fR()
  266. function, with the following additional error codes possible:
  267. .TP
  268. .BR EAGAIN
  269. The requested I/O operation was not queued due to resource limitations.
  270. .TP
  271. .BR ECANCELED
  272. The requested I/O was canceled before the I/O completed due to an
  273. explicit
  274. \fIaio_cancel\fR()
  275. request.
  276. .TP
  277. .BR EFBIG
  278. The \fIaiocbp\fP\->\fIaio_lio_opcode\fP is LIO_WRITE, the file is a
  279. regular file, \fIaiocbp\fP\->\fIaio_nbytes\fP is greater than 0, and
  280. the \fIaiocbp\fP\->\fIaio_offset\fP is greater than or equal to the
  281. offset maximum in the open file description associated with
  282. \fIaiocbp\fP\->\fIaio_fildes\fP.
  283. .TP
  284. .BR EINPROGRESS
  285. The requested I/O is in progress.
  286. .TP
  287. .BR EOVERFLOW
  288. The \fIaiocbp\fP\->\fIaio_lio_opcode\fP is LIO_READ, the file is a
  289. regular file, \fIaiocbp\fP\->\fIaio_nbytes\fP is greater than 0, and
  290. the \fIaiocbp\fP\->\fIaio_offset\fP is before the end-of-file and is
  291. greater than or equal to the offset maximum in the open file
  292. description associated with \fIaiocbp\fP\->\fIaio_fildes\fP.
  293. .LP
  294. .IR "The following sections are informative."
  295. .SH EXAMPLES
  296. None.
  297. .SH "APPLICATION USAGE"
  298. None.
  299. .SH RATIONALE
  300. Although it may appear that there are inconsistencies in the specified
  301. circumstances for error codes, the
  302. .BR [EIO]
  303. error condition applies when any circumstance relating to an individual
  304. operation makes that operation fail. This might be due to a badly
  305. formulated request (for example, the
  306. .IR aio_lio_opcode
  307. field is invalid, and
  308. \fIaio_error\fR()
  309. returns
  310. .BR [EINVAL] )
  311. or might arise from application behavior (for example, the file
  312. descriptor is closed before the operation is initiated, and
  313. \fIaio_error\fR()
  314. returns
  315. .BR [EBADF] ).
  316. .P
  317. The limitation on the set of error codes returned when operations from
  318. the list shall have been initiated enables applications to know when
  319. operations have been started and whether
  320. \fIaio_error\fR()
  321. is valid for a specific operation.
  322. .SH "FUTURE DIRECTIONS"
  323. None.
  324. .SH "SEE ALSO"
  325. .IR "\fIaio_read\fR\^(\|)",
  326. .IR "\fIaio_write\fR\^(\|)",
  327. .IR "\fIaio_error\fR\^(\|)",
  328. .IR "\fIaio_return\fR\^(\|)",
  329. .IR "\fIaio_cancel\fR\^(\|)",
  330. .IR "\fIclose\fR\^(\|)",
  331. .IR "\fIexec\fR\^",
  332. .IR "\fIexit\fR\^(\|)",
  333. .IR "\fIfork\fR\^(\|)",
  334. .IR "\fIlseek\fR\^(\|)",
  335. .IR "\fIread\fR\^(\|)"
  336. .P
  337. The Base Definitions volume of POSIX.1\(hy2017,
  338. .IR "\fB<aio.h>\fP"
  339. .\"
  340. .SH COPYRIGHT
  341. Portions of this text are reprinted and reproduced in electronic form
  342. from IEEE Std 1003.1-2017, Standard for Information Technology
  343. -- Portable Operating System Interface (POSIX), The Open Group Base
  344. Specifications Issue 7, 2018 Edition,
  345. Copyright (C) 2018 by the Institute of
  346. Electrical and Electronics Engineers, Inc and The Open Group.
  347. In the event of any discrepancy between this version and the original IEEE and
  348. The Open Group Standard, the original IEEE and The Open Group Standard
  349. is the referee document. The original Standard can be obtained online at
  350. http://www.opengroup.org/unix/online.html .
  351. .PP
  352. Any typographical or formatting errors that appear
  353. in this page are most likely
  354. to have been introduced during the conversion of the source files to
  355. man page format. To report such errors, see
  356. https://www.kernel.org/doc/man-pages/reporting_bugs.html .