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.Dd February 1, 2024 26.Dt AIO_WRITE 2 27.Os 28.Sh NAME 29.Nm aio_write , 30.Nm aio_write2 , 31.Nm aio_writev 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.Fn aio_write "struct aiocb *iocb" 39.Ft int 40.Fn aio_write2 "struct aiocb *iocb" "int flags" 41.In sys/uio.h 42.Ft int 43.Fn aio_writev "struct aiocb *iocb" 44.Sh DESCRIPTION 45The 46.Fn aio_write , 47.Fn aio_write2 , 48and 49.Fn aio_writev 50system calls allow the calling process to write 51to the descriptor 52.Fa iocb->aio_fildes . 53The syscalls return immediately after the write request has been enqueued 54to the descriptor; the write may or may not have completed at the time 55the call returns. 56.Pp 57The 58.Fn aio_write 59call will write 60.Fa iocb->aio_nbytes 61from the buffer pointed to by 62.Fa iocb->aio_buf , 63whereas 64.Fn aio_writev 65gathers the data from the 66.Fa iocb->aio_iovcnt 67buffers specified by the members of the 68.Fa iocb->aio_iov 69array. 70.Pp 71If the request could not be enqueued, generally due 72to invalid arguments, the call returns without having enqueued the 73request. 74.Pp 75For 76.Fn aio_writev 77the 78.Fa iovec 79structure is defined in 80.Xr writev 2 . 81.Pp 82If 83.Dv O_APPEND 84is set for 85.Fa iocb->aio_fildes , 86write operations append to the file in the same order as the calls were 87made. 88If 89.Dv O_APPEND 90is not set for the file descriptor, the write operation for 91.Fn aio_write 92will occur at 93the absolute position from the beginning of the file plus 94.Fa iocb->aio_offset . 95.Pp 96The 97.Fn aio_write2 98call takes the 99.Fa flags 100argument. 101If 102.Fa flags 103is passed as zero, the call behaves identically to 104.Fn aio_write . 105The following flags can be specified by logical or: 106.Bl -tag -width AIO_OP2_VECTORED 107.It AIO_OP2_FOFFSET 108The write for non 109.Dv O_APPEND 110file descriptors occurs at the file descriptor offset, 111which is advanced by the operation as done by the 112.Xr write 2 113syscall. 114The 115.Fa iocb->aio_offset 116field is ignored. 117.It AIO_OP2_VECTORED 118Similar to 119.Fn aio_writev , 120the write buffers are specified by the 121.Fa aiocb->aio_iov 122array. 123.El 124.Pp 125The 126.Fa iocb 127pointer may be subsequently used as an argument to 128.Fn aio_return 129and 130.Fn aio_error 131in order to determine return or error status for the enqueued operation 132while it is in progress. 133.Pp 134If the request is successfully enqueued, the value of 135.Fa iocb->aio_offset 136can be modified during the request as context, so this value must not 137be referenced after the request is enqueued. 138.Pp 139The 140.Fa iocb->aio_sigevent 141structure can be used to request notification of the operation's 142completion as described in 143.Xr aio 4 . 144.Sh RESTRICTIONS 145The Asynchronous I/O Control Block structure pointed to by 146.Fa iocb 147and the buffer that the 148.Fa iocb->aio_buf 149member of that structure references must remain valid until the 150operation has completed. 151.Pp 152The asynchronous I/O control buffer 153.Fa iocb 154should be zeroed before the 155system calls to avoid passing bogus context information to the kernel. 156.Pp 157Modifications of the Asynchronous I/O Control Block structure or the 158buffer contents are not allowed while the request is queued. 159.Pp 160If the file offset in 161.Fa iocb->aio_offset 162is past the offset maximum for 163.Fa iocb->aio_fildes , 164no I/O will occur. 165.Sh RETURN VALUES 166.Rv -std aio_write aio_writev 167.Sh ERRORS 168The 169.Fn aio_write , 170.Fn aio_write2 , 171and 172.Fn aio_writev 173system calls will fail if: 174.Bl -tag -width Er 175.It Bq Er EAGAIN 176The request was not queued because of system resource limitations. 177.It Bq Er EFAULT 178Part of 179.Fa aio_iov 180points outside the process's allocated address space. 181.It Bq Er EINVAL 182The asynchronous notification method in 183.Fa iocb->aio_sigevent.sigev_notify 184is invalid or not supported. 185.It Bq Er ENOSYS 186The 187.Fn aio_write 188system call is not supported. 189This can occur if 190.Xr aio 4 191support is not present. 192.It Bq Er EOPNOTSUPP 193Asynchronous write operations on the file descriptor 194.Fa iocb->aio_fildes 195are unsafe and unsafe asynchronous I/O operations are disabled. 196.El 197.Pp 198The following conditions may be synchronously detected when the 199.Fn aio_write , 200.Fn aio_write2 , 201or 202.Fn aio_writev 203system call is made, or asynchronously, at any time thereafter. 204If they 205are detected at call time, the calls return -1 and set 206.Va errno 207appropriately; otherwise the 208.Fn aio_return 209system call must be called, and will return -1, and 210.Fn aio_error 211must be called to determine the actual value that would have been 212returned in 213.Va errno . 214.Bl -tag -width Er 215.It Bq Er EBADF 216The 217.Fa iocb->aio_fildes 218argument 219is invalid, or is not opened for writing. 220.It Bq Er EINVAL 221The offset 222.Fa iocb->aio_offset 223is not valid, the priority specified by 224.Fa iocb->aio_reqprio 225is not a valid priority, or the number of bytes specified by 226.Fa iocb->aio_nbytes 227is not valid. 228.El 229.Pp 230If the request is successfully enqueued, but subsequently canceled 231or an error occurs, the value returned by the 232.Fn aio_return 233system call is per the 234.Xr write 2 235system call, and the value returned by the 236.Fn aio_error 237system call is either one of the error returns from the 238.Xr write 2 239system call, or one of: 240.Bl -tag -width Er 241.It Bq Er EBADF 242The 243.Fa iocb->aio_fildes 244argument 245is invalid for writing. 246.It Bq Er ECANCELED 247The request was explicitly canceled via a call to 248.Fn aio_cancel . 249.It Bq Er EINVAL 250The offset 251.Fa iocb->aio_offset 252would be invalid. 253.El 254.Sh SEE ALSO 255.Xr aio_cancel 2 , 256.Xr aio_error 2 , 257.Xr aio_return 2 , 258.Xr aio_suspend 2 , 259.Xr aio_waitcomplete 2 , 260.Xr sigevent 3 , 261.Xr siginfo 3 , 262.Xr aio 4 263.Sh STANDARDS 264The 265.Fn aio_write 266system call 267is expected to conform to the 268.St -p1003.1 269standard. 270.Pp 271The 272.Fn aio_write2 273and 274.Fn aio_writev 275system calls are 276.Fx 277extensions, 278and should not be used in portable code. 279.Sh HISTORY 280The 281.Fn aio_write 282system call first appeared in 283.Fx 3.0 . 284The 285.Fn aio_writev 286system call first appeared in 287.Fx 13.0 . 288The 289.Fn aio_write2 290system call first appeared in 291.Fx 14.1 . 292.Sh AUTHORS 293This manual page was written by 294.An Wes Peters Aq Mt wes@softweyr.com . 295.Sh BUGS 296Invalid information in 297.Fa iocb->_aiocb_private 298may confuse the kernel. 299