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