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 EOPNOTSUPP 186Asynchronous write operations on the file descriptor 187.Fa iocb->aio_fildes 188are unsafe and unsafe asynchronous I/O operations are disabled. 189.El 190.Pp 191The following conditions may be synchronously detected when the 192.Fn aio_write , 193.Fn aio_write2 , 194or 195.Fn aio_writev 196system call is made, or asynchronously, at any time thereafter. 197If they 198are detected at call time, the calls return -1 and set 199.Va errno 200appropriately; otherwise the 201.Fn aio_return 202system call must be called, and will return -1, and 203.Fn aio_error 204must be called to determine the actual value that would have been 205returned in 206.Va errno . 207.Bl -tag -width Er 208.It Bq Er EBADF 209The 210.Fa iocb->aio_fildes 211argument 212is invalid, or is not opened for writing. 213.It Bq Er EINVAL 214The offset 215.Fa iocb->aio_offset 216is not valid, the priority specified by 217.Fa iocb->aio_reqprio 218is not a valid priority, or the number of bytes specified by 219.Fa iocb->aio_nbytes 220is not valid. 221.El 222.Pp 223If the request is successfully enqueued, but subsequently canceled 224or an error occurs, the value returned by the 225.Fn aio_return 226system call is per the 227.Xr write 2 228system call, and the value returned by the 229.Fn aio_error 230system call is either one of the error returns from the 231.Xr write 2 232system call, or one of: 233.Bl -tag -width Er 234.It Bq Er EBADF 235The 236.Fa iocb->aio_fildes 237argument 238is invalid for writing. 239.It Bq Er ECANCELED 240The request was explicitly canceled via a call to 241.Fn aio_cancel . 242.It Bq Er EINVAL 243The offset 244.Fa iocb->aio_offset 245would be invalid. 246.El 247.Sh SEE ALSO 248.Xr aio_cancel 2 , 249.Xr aio_error 2 , 250.Xr aio_return 2 , 251.Xr aio_suspend 2 , 252.Xr aio_waitcomplete 2 , 253.Xr sigevent 3 , 254.Xr siginfo 3 , 255.Xr aio 4 256.Sh STANDARDS 257The 258.Fn aio_write 259system call 260is expected to conform to the 261.St -p1003.1 262standard. 263.Pp 264The 265.Fn aio_write2 266and 267.Fn aio_writev 268system calls are FreeBSD extensions, 269and should not be used in portable code. 270.Sh HISTORY 271The 272.Fn aio_write 273system call first appeared in 274.Fx 3.0 . 275The 276.Fn aio_writev 277system call first appeared in 278.Fx 13.0 . 279The 280.Fn aio_write2 281system call first appeared in 282.Fx 14.1 . 283.Sh AUTHORS 284This manual page was written by 285.An Wes Peters Aq Mt wes@softweyr.com . 286.Sh BUGS 287Invalid information in 288.Fa iocb->_aiocb_private 289may confuse the kernel. 290