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