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.4.2.5 2001/12/14 18:34:00 ru Exp $ 26.\" 27.Dd June 2, 1999 28.Dt AIO_WRITE 3 29.Os 30.Sh NAME 31.Nm aio_write 32.Nd asynchronous write to a file (REALTIME) 33.Sh LIBRARY 34.Lb librt 35.Sh SYNOPSIS 36.In 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 function returns immediately after the write request has been enqueued 49to the descriptor; the write may or may not have completed at the time 50the function returns. 51If the request could not be enqueued, generally due 52to invalid arguments, the function returns without having enqueued the 53request. 54.Pp 55If 56.Dv O_APPEND 57is set for 58.Fa iocb->aio_fildes , 59.Fn aio_write 60operations append to the file in the same order as the calls were 61made. 62If 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 iocb->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 iocb->aio_reqprio . 74.Pp 75The 76.Fa iocb 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 iocb->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 iocb 91and the buffer that the 92.Fa iocb->aio_buf 93member of that structure references must remain valid until the 94operation has completed. 95For this reason, use of auto (stack) variables 96for these objects is discouraged. 97.Pp 98The asynchronous I/O control buffer 99.Fa iocb 100should be zeroed before the 101.Fn aio_write 102function. 103.Pp 104Modifications of the Asynchronous I/O Control Block structure or the 105buffer contents after the request has been enqueued, but before the 106request has completed, are not allowed. 107.Pp 108If the file offset in 109.Fa iocb->aio_offset 110is past the offset maximum for 111.Fa iocb->aio_fildes , 112no I/O will occur. 113.Sh RETURN VALUES 114.Rv -std aio_write 115.Sh ERRORS 116The 117.Fn aio_write 118function will fail if: 119.Bl -tag -width Er 120.It Bq Er EAGAIN 121The request was not queued because of system resource limitations. 122.It Bq Er ENOSYS 123The 124.Fn aio_write 125function is not supported. 126.El 127.Pp 128The following conditions may be synchronously detected when the 129.Fn aio_write 130function is made, or asynchronously, at any time thereafter. 131If they are detected at call time, 132.Fn aio_write 133returns -1 and sets 134.Va errno 135appropriately; otherwise the 136.Fn aio_return 137function must be called, and will return -1, and 138.Fn aio_error 139must be called to determine the actual value that would have been 140returned in 141.Va errno . 142.Bl -tag -width Er 143.It Bq Er EBADF 144.Fa iocb->aio_fildes 145is invalid, or is not opened for writing. 146.It Bq Er EINVAL 147The offset 148.Fa iocb->aio_offset 149is not valid, the priority specified by 150.Fa iocb->aio_reqprio 151is not a valid priority, or the number of bytes specified by 152.Fa iocb->aio_nbytes 153is not valid. 154.El 155.Pp 156If the request is successfully enqueued, but subsequently canceled 157or an error occurs, the value returned by the 158.Fn aio_return 159function is per the 160.Xr write 2 161call, and the value returned by the 162.Fn aio_error 163function is either one of the error returns from the 164.Xr write 2 165call, or one of: 166.Bl -tag -width Er 167.It Bq Er EBADF 168.Fa iocb->aio_fildes 169is invalid for writing. 170.It Bq Er ECANCELED 171The request was explicitly canceled via a call to 172.Fn aio_cancel . 173.It Bq Er EINVAL 174The offset 175.Fa iocb->aio_offset 176would be invalid. 177.El 178.Sh STANDARDS 179.Fn aio_write 180is expected to conform to the 181.St -p1003.2 182standard. 183.Sh HISTORY 184The 185.Nm 186function first appeared in 187.Fx 3.0 . 188.Sh AUTHORS 189This manual page was written by 190.An Wes Peters Aq Mt wes@softweyr.com . 191.Sh BUGS 192Asynchronous I/O operations cannot be canceled in this implementation. 193