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_write.3p (7064B)


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