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

aio_read.3p (6839B)


  1. '\" et
  2. .TH AIO_READ "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. aio_read
  12. \(em asynchronous read from a file
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <aio.h>
  17. .P
  18. int aio_read(struct aiocb *\fIaiocbp\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fIaio_read\fR()
  23. function shall read \fIaiocbp\fP\->\fIaio_nbytes\fR from the file
  24. associated with \fIaiocbp\fP\->\fIaio_fildes\fR into the buffer pointed
  25. to by \fIaiocbp\fP\->\fIaio_buf\fR. The function call shall return when
  26. the read request has been initiated or queued to the file or device
  27. (even when the data cannot be delivered immediately).
  28. .P
  29. If prioritized I/O is supported for this file, then the asynchronous
  30. operation shall be submitted at a priority equal to a base scheduling
  31. priority minus \fIaiocbp\fP\->\fIaio_reqprio\fR. If Thread Execution
  32. Scheduling is not supported, then the base scheduling priority is that
  33. of the calling process;
  34. .br
  35. otherwise, the base scheduling priority is that of the calling thread.
  36. .P
  37. The
  38. .IR aiocbp
  39. value may be used as an argument to
  40. \fIaio_error\fR()
  41. and
  42. \fIaio_return\fR()
  43. in order to determine the error status and return status, respectively,
  44. of the asynchronous operation while it is proceeding. If an error
  45. condition is encountered during queuing, the function call shall return
  46. without having initiated or queued the request. The requested
  47. operation takes place at the absolute position in the file as given by
  48. .IR aio_offset ,
  49. as if
  50. \fIlseek\fR()
  51. were called immediately prior to the operation with an
  52. .IR offset
  53. equal to
  54. .IR aio_offset
  55. and a
  56. .IR whence
  57. equal to SEEK_SET.
  58. After a successful call to enqueue an asynchronous I/O operation, the
  59. value of the file offset for the file is unspecified.
  60. .P
  61. The
  62. .IR aio_sigevent
  63. member specifies the notification which occurs when the request is
  64. completed.
  65. .P
  66. The \fIaiocbp\fP\->\fIaio_lio_opcode\fR field shall be ignored by
  67. \fIaio_read\fR().
  68. .P
  69. The
  70. .IR aiocbp
  71. argument points to an
  72. .BR aiocb
  73. structure. If the buffer pointed to by \fIaiocbp\fP\->\fIaio_buf\fR or
  74. the control block pointed to by
  75. .IR aiocbp
  76. becomes an illegal address prior to asynchronous I/O completion, then
  77. the behavior is undefined.
  78. .P
  79. Simultaneous asynchronous operations using the same
  80. .IR aiocbp
  81. produce undefined results.
  82. .P
  83. If synchronized I/O is enabled on the file associated with
  84. \fIaiocbp\fP\->\fIaio_fildes\fR, the behavior of this function shall
  85. be according to the definitions of synchronized I/O data integrity
  86. completion and synchronized I/O file integrity completion.
  87. .P
  88. For any system action that changes the process memory space while an
  89. asynchronous I/O is outstanding to the address range being changed, the
  90. result of that action is undefined.
  91. .P
  92. For regular files, no data transfer shall occur past the offset maximum
  93. established in the open file description associated with
  94. \fIaiocbp\fP\->\fIaio_fildes\fR.
  95. .SH "RETURN VALUE"
  96. The
  97. \fIaio_read\fR()
  98. function shall return the value zero if the I/O operation is
  99. successfully queued; otherwise, the function shall return the value
  100. \-1 and set
  101. .IR errno
  102. to indicate the error.
  103. .SH ERRORS
  104. The
  105. \fIaio_read\fR()
  106. function shall fail if:
  107. .TP
  108. .BR EAGAIN
  109. The requested asynchronous I/O operation was not queued due to system
  110. resource limitations.
  111. .P
  112. Each of the following conditions may be detected synchronously at the
  113. time of the call to
  114. \fIaio_read\fR(),
  115. or asynchronously. If any of the conditions below are detected
  116. synchronously, the
  117. \fIaio_read\fR()
  118. function shall return \-1 and set
  119. .IR errno
  120. to the corresponding value. If any of the conditions below are
  121. detected asynchronously, the return status of the asynchronous
  122. operation is set to \-1, and the error status of the asynchronous
  123. operation is set to the corresponding value.
  124. .TP
  125. .BR EBADF
  126. The \fIaiocbp\fP\->\fIaio_fildes\fP argument is not a valid file
  127. descriptor open for reading.
  128. .TP
  129. .BR EINVAL
  130. The file offset value implied by \fIaiocbp\fP\->\fIaio_offset\fR would
  131. be invalid,
  132. .br
  133. \fIaiocbp\fP\->\fIaio_reqprio\fR is not a valid value,
  134. or \fIaiocbp\fP\->\fIaio_nbytes\fR is an invalid value.
  135. .P
  136. In the case that the
  137. \fIaio_read\fR()
  138. successfully queues the I/O operation but the operation is subsequently
  139. canceled or encounters an error, the return status of the asynchronous
  140. operation is one of the values normally returned by the
  141. \fIread\fR()
  142. function call. In addition, the error status of the asynchronous
  143. operation is set to one of the error statuses normally set by the
  144. \fIread\fR()
  145. function call, or one of the following values:
  146. .TP
  147. .BR EBADF
  148. The \fIaiocbp\fP\->\fIaio_fildes\fR argument is not a valid file
  149. descriptor open for reading.
  150. .TP
  151. .BR ECANCELED
  152. The requested I/O was canceled before the I/O completed due to an
  153. explicit
  154. \fIaio_cancel\fR()
  155. request.
  156. .TP
  157. .BR EINVAL
  158. The file offset value implied by \fIaiocbp\fP\->\fIaio_offset\fR would
  159. be invalid.
  160. .P
  161. The following condition may be detected synchronously or asynchronously:
  162. .TP
  163. .BR EOVERFLOW
  164. The file is a regular file, \fIaiobcp\fP\->\fIaio_nbytes\fR is greater
  165. than 0, and the starting offset in \fIaiobcp\fP\->\fIaio_offset\fR is
  166. before the end-of-file and is at or beyond the offset maximum in the
  167. open file description associated with \fIaiocbp\fP\->\fIaio_fildes\fR.
  168. .LP
  169. .IR "The following sections are informative."
  170. .SH EXAMPLES
  171. None.
  172. .SH "APPLICATION USAGE"
  173. None.
  174. .SH RATIONALE
  175. None.
  176. .SH "FUTURE DIRECTIONS"
  177. None.
  178. .SH "SEE ALSO"
  179. .IR "\fIaio_cancel\fR\^(\|)",
  180. .IR "\fIaio_error\fR\^(\|)",
  181. .IR "\fIlio_listio\fR\^(\|)",
  182. .IR "\fIaio_return\fR\^(\|)",
  183. .IR "\fIaio_write\fR\^(\|)",
  184. .IR "\fIclose\fR\^(\|)",
  185. .IR "\fIexec\fR\^",
  186. .IR "\fIexit\fR\^(\|)",
  187. .IR "\fIfork\fR\^(\|)",
  188. .IR "\fIlseek\fR\^(\|)",
  189. .IR "\fIread\fR\^(\|)"
  190. .P
  191. The Base Definitions volume of POSIX.1\(hy2017,
  192. .IR "\fB<aio.h>\fP"
  193. .\"
  194. .SH COPYRIGHT
  195. Portions of this text are reprinted and reproduced in electronic form
  196. from IEEE Std 1003.1-2017, Standard for Information Technology
  197. -- Portable Operating System Interface (POSIX), The Open Group Base
  198. Specifications Issue 7, 2018 Edition,
  199. Copyright (C) 2018 by the Institute of
  200. Electrical and Electronics Engineers, Inc and The Open Group.
  201. In the event of any discrepancy between this version and the original IEEE and
  202. The Open Group Standard, the original IEEE and The Open Group Standard
  203. is the referee document. The original Standard can be obtained online at
  204. http://www.opengroup.org/unix/online.html .
  205. .PP
  206. Any typographical or formatting errors that appear
  207. in this page are most likely
  208. to have been introduced during the conversion of the source files to
  209. man page format. To report such errors, see
  210. https://www.kernel.org/doc/man-pages/reporting_bugs.html .