1.\" Copyright (c) 1999 Softweyr LLC. 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY Softweyr LLC AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL Softweyr LLC OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD: src/lib/libc/sys/aio_write.2,v 1.16 2003/01/13 10:37:11 tjr Exp $ 26.\" 27.Dd September 18, 2008 28.Dt AIO_WRITE 2 29.Os 30.Sh NAME 31.Nm aio_write 32.Nd asynchronous write to a file (REALTIME) 33.Sh LIBRARY 34.Lb libc 35.Sh SYNOPSIS 36.In aio.h 37.Ft int 38.Fo aio_write 39.Fa "struct aiocb *aiocbp" 40.Fc 41.Sh DESCRIPTION 42The 43.Fn aio_write 44system call allows the calling process to write 45.Fa aiocbp->aio_nbytes 46from the buffer pointed to by 47.Fa aiocbp->aio_buf 48to the descriptor 49.Fa aiocbp->aio_fildes . 50The call returns immediately after the write request has been enqueued 51to the descriptor; the write may or may not have completed at the time 52the call returns. If the request could not be enqueued, generally due 53to invalid arguments, the call returns without having enqueued the 54request. 55.Pp 56If 57.Dv O_APPEND 58is set for 59.Fa aiocbp->aio_fildes , 60.Fn aio_write 61operations append to the file in the same order as the calls were 62made. If 63.Dv O_APPEND 64is not set for the file descriptor, the write operation will occur at 65the absolute position from the beginning of the file plus 66.Fa aiocbp->aio_offset . 67.Pp 68If 69.Dv _POSIX_PRIORITIZED_IO 70is defined, and the descriptor supports it, then the enqueued 71operation is submitted at a priority equal to that of the calling 72process minus 73.Fa aiocbp->aio_reqprio . 74.Pp 75The 76.Fa aiocbp 77pointer may be subsequently used as an argument to 78.Fn aio_return 79and 80.Fn aio_error 81in order to determine return or error status for the enqueued operation 82while it is in progress. 83.Pp 84If the request is successfully enqueued, the value of 85.Fa aiocbp->aio_offset 86can be modified during the request as context, so this value must not 87be referenced after the request is enqueued. 88.Sh RESTRICTIONS 89The Asynchronous I/O Control Block structure pointed to by 90.Fa aiocbp 91and the buffer that the 92.Fa aiocbp->aio_buf 93member of that structure references must remain valid until the 94operation has completed. For this reason, use of auto (stack) variables 95for these objects is discouraged. 96.Pp 97The asynchronous I/O control buffer 98.Fa aiocbp 99should be zeroed before the 100.Fn aio_write 101system call to avoid passing bogus context information to the kernel. 102.Pp 103Modifications of the Asynchronous I/O Control Block structure or the 104buffer contents after the request has been enqueued, but before the 105request has completed, are not allowed. 106.Pp 107If the file offset in 108.Fa aiocbp->aio_offset 109is past the offset maximum for 110.Fa aiocbp->aio_fildes , 111no I/O will occur. 112.Sh RETURN VALUES 113.Rv -std aio_write 114.Sh ERRORS 115The 116.Fn aio_write 117system call will fail if: 118.Bl -tag -width Er 119.\" ========== 120.It Bq Er EAGAIN 121Due to system resource limitations, 122the request was not queued. 123.\" ========== 124.It Bq Er ENOSYS 125The 126.Fn aio_write 127system call is not supported. 128.El 129.Pp 130The following conditions may be synchronously detected when the 131.Fn aio_write 132system call is made, or asynchronously, at any time thereafter. If they 133are detected at call time, 134.Fn aio_write 135returns -1 and sets 136.Va errno 137appropriately; otherwise the 138.Fn aio_return 139system call must be called, and will return -1, and 140.Fn aio_error 141must be called to determine the actual value that would have been 142returned in 143.Va errno . 144.Pp 145.Bl -tag -width Er 146.\" ========== 147.It Bq Er EBADF 148The 149.Fa aiocbp->aio_fildes 150argument 151is invalid, or is not opened for writing. 152.\" ========== 153.It Bq Er EINVAL 154The offset 155.Fa aiocbp->aio_offset 156is not valid. 157.\" ========== 158.It Bq Er EINVAL 159The priority specified by 160.Fa aiocbp->aio_reqprio 161is not a valid priority. 162.\" ========== 163.It Bq Er EINVAL 164The number of bytes specified by 165.Fa aiocbp->aio_nbytes 166is not valid. 167.\" ========== 168.It Bq Er EINVAL 169The constant in 170.Fa aiocbp->aio_sigevent.sigev_notify 171is set to SIGEV_THREAD (SIGEV_THREAD is not supported). 172.El 173.Pp 174If the request is successfully enqueued, but subsequently canceled 175or an error occurs, the value returned by the 176.Fn aio_return 177system call is per the 178.Xr write 2 179system call, and the value returned by the 180.Fn aio_error 181system call is either one of the error returns from the 182.Xr write 2 183system call, or one of: 184.Bl -tag -width Er 185.\" ========== 186.It Bq Er EBADF 187The 188.Fa aiocbp->aio_fildes 189argument 190is invalid for writing. 191.\" ========== 192.It Bq Er ECANCELED 193The request was explicitly canceled via a call to 194.Fn aio_cancel . 195.El 196.Sh SEE ALSO 197.Xr aio_cancel 2 , 198.Xr aio_error 2 , 199.Xr aio_return 2 , 200.Xr aio_suspend 2 , 201.Xr aio 4 202.Sh STANDARDS 203The 204.Fn aio_write 205system call 206is expected to conform to the 207.St -p1003.1 208standard. 209.Sh HISTORY 210The 211.Fn aio_write 212system call first appeared in 213.Fx 3.0 . 214.Sh AUTHORS 215This manual page was written by 216.An Wes Peters Aq [email protected] . 217.Sh BUGS 218Invalid information in 219.Fa aiocbp->_aiocb_private 220may confuse the kernel. 221