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$ 26.\" 27.Dd June 2, 1999 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.Fd #include <aio.h> 37.Ft int 38.Fn aio_write "struct aiocb *iocb" 39.Sh DESCRIPTION 40The 41.Fn aio_write 42function allows the calling process to write 43.Fa iocb->aio_nbytes 44from the buffer pointed to by 45.Fa iocb->aio_buf 46to the descriptor 47.Fa iocb->aio_fildes . 48The call returns immediately after the write request has been enqueued 49to the descriptor; the write may or may not have completed at the time 50the call returns. If the request could not be enqueued, generally due 51to invalid arguments, the call returns without having enqueued the 52request. 53.Pp 54If 55.Dv O_APPEND 56is set for 57.Fa iocb->aio_fildes , 58.Fn aio_write 59operations append to the file in the same order as the calls were 60made. If 61.Dv O_APPEND 62is not set for the file descriptor, the write operation will occur at 63the absolute position from the beginning of the file plus 64.Fa iocb->aio_offset . 65.Pp 66If 67.Dv _POSIX_PRIORITIZED_IO 68is defined, and the descriptor supports it, then the enqueued 69operation is submitted at a priority equal to that of the calling 70process minus 71.Fa iocb->aio_reqprio . 72.Pp 73The 74.Fa iocb 75pointer may be subsequently used as an argument to 76.Fn aio_return 77and 78.Fn aio_error 79in order to determine return or error status for the enqueued operation 80while it is in progress. 81.Pp 82If the request is successfully enqueued, the value of 83.Fa iocb->aio_offset 84can be modified during the request as context, so this value must not 85be referenced after the request is enqueued. 86.Sh RESTRICTIONS 87The Asynchronous I/O Control Block structure pointed to by 88.Fa iocb 89and the buffer that the 90.Fa iocb->aio_buf 91member of that structure references must remain valid until the 92operation has completed. For this reason, use of auto (stack) variables 93for these objects is discouraged. 94.Pp 95The asynchronous I/O control buffer 96.Fa iocb 97should be zeroed before the 98.Fn aio_read 99call to avoid passing bogus context information to the kernel. 100.Pp 101Modifications of the Asynchronous I/O Control Block structure or the 102buffer contents after the request has been enqueued, but before the 103request has completed, are not allowed. 104.Pp 105If the file offset in 106.Fa iocb->aio_offset 107is past the offset maximum for 108.Fa iocb->aio_fildes , 109no I/O will occur. 110.Sh RETURN VALUES 111.Rv -std aio_write 112.Sh ERRORS 113The 114.Fn aio_write 115function will fail if: 116.Bl -tag -width Er 117.It Bq Er EAGAIN 118The request was not queued because of system resource limitations. 119.It Bq Er ENOSYS 120The 121.Fn aio_write 122call is not supported. 123.El 124.Pp 125The following conditions may be synchronously detected when the 126.Fn aio_write 127call is made, or asynchronously, at any time thereafter. If they 128are detected at call time, 129.Fn aio_write 130returns -1 and sets 131.Va errno 132appropriately; otherwise the 133.Fn aio_return 134function must be called, and will return -1, and 135.Fn aio_error 136must be called to determine the actual value that would have been 137returned in 138.Va errno . 139.Pp 140.Bl -tag -width Er 141.It Bq Er EBADF 142.Fa iocb->aio_fildes 143is invalid, or is not opened for writing. 144.It Bq Er EINVAL 145The offset 146.Fa iocb->aio_offset 147is not valid, the priority specified by 148.Fa iocb->aio_reqprio 149is not a valid priority, or the number of bytes specified by 150.Fa iocb->aio_nbytes 151is not valid. 152.El 153.Pp 154If the request is successfully enqueued, but subsequently canceled 155or an error occurs, the value returned by the 156.Fn aio_return 157function is per the 158.Xr write 2 159call, and the value returned by the 160.Fn aio_error 161function is either one of the error returns from the 162.Xr write 2 163call, or one of: 164.Bl -tag -width Er 165.It Bq Er EBADF 166.Fa iocb->aio_fildes 167is invalid for writing. 168.It Bq Er ECANCELED 169The request was explicitly canceled via a call to 170.Fn aio_cancel . 171.It Bq Er EINVAL 172The offset 173.Fa iocb->aio_offset 174would be invalid. 175.El 176.Sh STANDARDS 177.Fn aio_write 178is expected to conform to the 179.St -p1003.2 180standard. 181.Sh HISTORY 182The 183.Nm 184Function first appeared in 185.Fx 3.0 . 186.Sh AUTHORS 187This manual page was written by 188.An Wes Peters Aq [email protected] . 189.Sh BUGS 190Invalid information in 191.Fa iocb->_aiocb_private 192may confuse the kernel. 193