--- name: "aio_write2" section: "2" platform: "freebsd" package: "base" version: "16.0-CURRENT-20261027-61c70dc16a79" release: "FreeBSD 16.0-CURRENT (2026-10-27)" platforms: ["freebsd"] url: "https://new.carta.tech/aio_write" --- # aio\_write2(2) asynchronous write to a file (REALTIME) Part of [aio\_write(2)](/aio_write/2.md). ## NAME **aio\_write**, **aio\_write2**, **aio\_writev** – asynchronous write to a file (REALTIME) ## LIBRARY Standard C Library (libc, -lc) ## SYNOPSIS **#include \** *int*\ **aio\_write**(*struct aiocb \*iocb*); *int*\ **aio\_write2**(*struct aiocb \*iocb*, *int flags*); **#include \** *int*\ **aio\_writev**(*struct aiocb \*iocb*); ## DESCRIPTION The **aio\_write**(), **aio\_write2**(), and **aio\_writev**() system calls allow the calling process to write to the descriptor *iocb-\>aio\_fildes*. The syscalls return immediately after the write request has been enqueued to the descriptor; the write may or may not have completed at the time the call returns. The **aio\_write**() call will write *iocb-\>aio\_nbytes* from the buffer pointed to by *iocb-\>aio\_buf*, whereas **aio\_writev**() gathers the data from the *iocb-\>aio\_iovcnt* buffers specified by the members of the *iocb-\>aio\_iov* array. If the request could not be enqueued, generally due to invalid arguments, the call returns without having enqueued the request. For **aio\_writev**() the *iovec* structure is defined in [writev(2)](/writev/2.md). If O\_APPEND is set for *iocb-\>aio\_fildes*, write operations append to the file in the same order as the calls were made. If O\_APPEND is not set for the file descriptor, the write operation for **aio\_write**() will occur at the absolute position from the beginning of the file plus *iocb-\>aio\_offset*. The **aio\_write2**() call takes the *flags* argument. If *flags* is passed as zero, the call behaves identically to **aio\_write**(). The following flags can be specified by logical or: - AIO\_OP2\_FOFFSET The write for non O\_APPEND file descriptors occurs at the file descriptor offset, which is advanced by the operation as done by the [write(2)](/write/2.md) syscall. The *iocb-\>aio\_offset* field is ignored. - AIO\_OP2\_VECTORED Similar to **aio\_writev**(), the write buffers are specified by the *aiocb-\>aio\_iov* array. The *iocb* pointer may be subsequently used as an argument to **aio\_return**() and **aio\_error**() in order to determine return or error status for the enqueued operation while it is in progress. If the request is successfully enqueued, the value of *iocb-\>aio\_offset* can be modified during the request as context, so this value must not be referenced after the request is enqueued. The *iocb-\>aio\_sigevent* structure can be used to request notification of the operation's completion as described in [aio(4)](/aio/4.md). ## RESTRICTIONS The Asynchronous I/O Control Block structure pointed to by *iocb* and the buffer that the *iocb-\>aio\_buf* member of that structure references must remain valid until the operation has completed. The asynchronous I/O control buffer *iocb* should be zeroed before the system calls to avoid passing bogus context information to the kernel. Modifications of the Asynchronous I/O Control Block structure or the buffer contents are not allowed while the request is queued. If the file offset in *iocb-\>aio\_offset* is past the offset maximum for *iocb-\>aio\_fildes*, no I/O will occur. ## RETURN VALUES The **aio\_write()** and **aio\_writev()** functions return the value 0 if successful; otherwise the value -1 is returned and the global variable errno is set to indicate the error. ## ERRORS The **aio\_write**(), **aio\_write2**(), and **aio\_writev**() system calls will fail if: - \[EAGAIN\] The request was not queued because of system resource limitations. - \[EFAULT\] Part of *aio\_iov* points outside the process's allocated address space. - \[EINVAL\] The asynchronous notification method in *iocb-\>aio\_sigevent.sigev\_notify* is invalid or not supported. - \[EOPNOTSUPP\] Asynchronous write operations on the file descriptor *iocb-\>aio\_fildes* are unsafe and unsafe asynchronous I/O operations are disabled. The following conditions may be synchronously detected when the **aio\_write**(), **aio\_write2**(), or **aio\_writev**() system call is made, or asynchronously, at any time thereafter. If they are detected at call time, the calls return -1 and set *errno* appropriately; otherwise the **aio\_return**() system call must be called, and will return -1, and **aio\_error**() must be called to determine the actual value that would have been returned in *errno*. - \[EBADF\] The *iocb-\>aio\_fildes* argument is invalid, or is not opened for writing. - \[EINVAL\] The offset *iocb-\>aio\_offset* is not valid, the priority specified by *iocb-\>aio\_reqprio* is not a valid priority, or the number of bytes specified by *iocb-\>aio\_nbytes* is not valid. If the request is successfully enqueued, but subsequently canceled or an error occurs, the value returned by the **aio\_return**() system call is per the [write(2)](/write/2.md) system call, and the value returned by the **aio\_error**() system call is either one of the error returns from the [write(2)](/write/2.md) system call, or one of: - \[EBADF\] The *iocb-\>aio\_fildes* argument is invalid for writing. - \[ECANCELED\] The request was explicitly canceled via a call to **aio\_cancel**(). - \[EINVAL\] The offset *iocb-\>aio\_offset* would be invalid. ## SEE ALSO [aio\_cancel(2)](/aio_cancel/2.md), [aio\_error(2)](/aio_error/2.md), [aio\_return(2)](/aio_return/2.md), [aio\_suspend(2)](/aio_suspend/2.md), [aio\_waitcomplete(2)](/aio_waitcomplete/2.md), [sigevent(3)](/sigevent/3.md), [siginfo(3)](/siginfo/3.md), [aio(4)](/aio/4.md) ## STANDARDS The **aio\_write**() system call is expected to conform to the IEEE Std 1003.1 (“POSIX.1”) standard. The **aio\_write2**() and **aio\_writev**() system calls are FreeBSD extensions, and should not be used in portable code. ## HISTORY The **aio\_write**() system call first appeared in FreeBSD 3.0. The **aio\_writev**() system call first appeared in FreeBSD 13.0. The **aio\_write2**() system call first appeared in FreeBSD 14.1. ## AUTHORS This manual page was written by Wes Peters ⟨*wes@softweyr.com*⟩. ## BUGS Invalid information in *iocb-\>\_aiocb\_private* may confuse the kernel.