Changeset View
Changeset View
Standalone View
Standalone View
lib/libc/sys/aio_write.2
Show All 18 Lines | |||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | ||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | ||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | ||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | ||||
.\" SUCH DAMAGE. | .\" SUCH DAMAGE. | ||||
.\" | .\" | ||||
.\" $FreeBSD$ | .\" $FreeBSD$ | ||||
.\" | .\" | ||||
.Dd August 19, 2016 | .Dd November 29, 2020 | ||||
.Dt AIO_WRITE 2 | .Dt AIO_WRITE 2 | ||||
.Os | .Os | ||||
.Sh NAME | .Sh NAME | ||||
.Nm aio_write | .Nm aio_write , | ||||
.Nm aio_writev | |||||
.Nd asynchronous write to a file (REALTIME) | .Nd asynchronous write to a file (REALTIME) | ||||
.Sh LIBRARY | .Sh LIBRARY | ||||
.Lb libc | .Lb libc | ||||
.Sh SYNOPSIS | .Sh SYNOPSIS | ||||
.In aio.h | .In aio.h | ||||
.Ft int | .Ft int | ||||
.Fn aio_write "struct aiocb *iocb" | .Fn aio_write "struct aiocb *iocb" | ||||
.Ft int | |||||
.Fn aio_writev "struct aiocb *iocb" | |||||
.Sh DESCRIPTION | .Sh DESCRIPTION | ||||
The | The | ||||
.Fn aio_write | .Fn aio_write | ||||
system call allows the calling process to write | and | ||||
.Fa iocb->aio_nbytes | .Fn aio_writev | ||||
from the buffer pointed to by | system calls allow the calling process to write | ||||
.Fa iocb->aio_buf | |||||
to the descriptor | to the descriptor | ||||
.Fa iocb->aio_fildes . | .Fa iocb->aio_fildes . | ||||
The call returns immediately after the write request has been enqueued | .Fn aio_write | ||||
will write | |||||
.Fa iocb->aio_nbytes | |||||
from the buffer pointed to by | |||||
.Fa iocb->aio_buf , | |||||
whereas | |||||
.Fn aio_writev | |||||
gathers the data from the | |||||
.Fa iocb->aio_iovcnt | |||||
buffers specified by the members of the | |||||
.Fa iocb->aio_iov | |||||
array. | |||||
Both syscalls return immediately after the write request has been enqueued | |||||
to the descriptor; the write may or may not have completed at the time | to the descriptor; the write may or may not have completed at the time | ||||
the call returns. | the call returns. | ||||
If the request could not be enqueued, generally due | If the request could not be enqueued, generally due | ||||
to invalid arguments, the call returns without having enqueued the | to invalid arguments, the call returns without having enqueued the | ||||
request. | request. | ||||
.Pp | .Pp | ||||
For | |||||
.Fn aio_writev | |||||
the | |||||
.Fa iovec | |||||
structure is defined in | |||||
.Xr writev 2 . | |||||
.Pp | |||||
If | If | ||||
.Dv O_APPEND | .Dv O_APPEND | ||||
is set for | is set for | ||||
.Fa iocb->aio_fildes , | .Fa iocb->aio_fildes , | ||||
.Fn aio_write | write operations append to the file in the same order as the calls were | ||||
operations append to the file in the same order as the calls were | |||||
made. | made. | ||||
If | If | ||||
.Dv O_APPEND | .Dv O_APPEND | ||||
is not set for the file descriptor, the write operation will occur at | is not set for the file descriptor, the write operation will occur at | ||||
the absolute position from the beginning of the file plus | the absolute position from the beginning of the file plus | ||||
.Fa iocb->aio_offset . | .Fa iocb->aio_offset . | ||||
.Pp | .Pp | ||||
If | If | ||||
Show All 29 Lines | |||||
.Fa iocb->aio_buf | .Fa iocb->aio_buf | ||||
member of that structure references must remain valid until the | member of that structure references must remain valid until the | ||||
operation has completed. | operation has completed. | ||||
.Pp | .Pp | ||||
The asynchronous I/O control buffer | The asynchronous I/O control buffer | ||||
.Fa iocb | .Fa iocb | ||||
should be zeroed before the | should be zeroed before the | ||||
.Fn aio_write | .Fn aio_write | ||||
or | |||||
.Fn aio_writev | |||||
system call to avoid passing bogus context information to the kernel. | system call to avoid passing bogus context information to the kernel. | ||||
.Pp | .Pp | ||||
Modifications of the Asynchronous I/O Control Block structure or the | Modifications of the Asynchronous I/O Control Block structure or the | ||||
buffer contents are not allowed while the request is queued. | buffer contents are not allowed while the request is queued. | ||||
.Pp | .Pp | ||||
If the file offset in | If the file offset in | ||||
.Fa iocb->aio_offset | .Fa iocb->aio_offset | ||||
is past the offset maximum for | is past the offset maximum for | ||||
.Fa iocb->aio_fildes , | .Fa iocb->aio_fildes , | ||||
no I/O will occur. | no I/O will occur. | ||||
.Sh RETURN VALUES | .Sh RETURN VALUES | ||||
.Rv -std aio_write | .Rv -std aio_write aio_writev | ||||
.Sh ERRORS | .Sh ERRORS | ||||
The | The | ||||
.Fn aio_write | .Fn aio_write | ||||
system call will fail if: | and | ||||
.Fn aio_writev | |||||
system calls will fail if: | |||||
.Bl -tag -width Er | .Bl -tag -width Er | ||||
.It Bq Er EAGAIN | .It Bq Er EAGAIN | ||||
The request was not queued because of system resource limitations. | The request was not queued because of system resource limitations. | ||||
.It Bq Er EFAULT | |||||
Part of | |||||
.Fa aio_iov | |||||
points outside the process's allocated address space. | |||||
.It Bq Er EINVAL | .It Bq Er EINVAL | ||||
The asynchronous notification method in | The asynchronous notification method in | ||||
.Fa iocb->aio_sigevent.sigev_notify | .Fa iocb->aio_sigevent.sigev_notify | ||||
is invalid or not supported. | is invalid or not supported. | ||||
.It Bq Er EOPNOTSUPP | .It Bq Er EOPNOTSUPP | ||||
Asynchronous write operations on the file descriptor | Asynchronous write operations on the file descriptor | ||||
.Fa iocb->aio_fildes | .Fa iocb->aio_fildes | ||||
are unsafe and unsafe asynchronous I/O operations are disabled. | are unsafe and unsafe asynchronous I/O operations are disabled. | ||||
.El | .El | ||||
.Pp | .Pp | ||||
The following conditions may be synchronously detected when the | The following conditions may be synchronously detected when the | ||||
.Fn aio_write | .Fn aio_write | ||||
or | |||||
.Fn aio_writev | |||||
system call is made, or asynchronously, at any time thereafter. | system call is made, or asynchronously, at any time thereafter. | ||||
If they | If they | ||||
are detected at call time, | are detected at call time, | ||||
.Fn aio_write | .Fn aio_write | ||||
or | |||||
.Fn aio_writev | |||||
returns -1 and sets | returns -1 and sets | ||||
.Va errno | .Va errno | ||||
appropriately; otherwise the | appropriately; otherwise the | ||||
.Fn aio_return | .Fn aio_return | ||||
system call must be called, and will return -1, and | system call must be called, and will return -1, and | ||||
.Fn aio_error | .Fn aio_error | ||||
must be called to determine the actual value that would have been | must be called to determine the actual value that would have been | ||||
returned in | returned in | ||||
▲ Show 20 Lines • Show All 49 Lines • ▼ Show 20 Lines | |||||
.Xr aio 4 | .Xr aio 4 | ||||
.Sh STANDARDS | .Sh STANDARDS | ||||
The | The | ||||
.Fn aio_write | .Fn aio_write | ||||
system call | system call | ||||
is expected to conform to the | is expected to conform to the | ||||
.St -p1003.1 | .St -p1003.1 | ||||
standard. | standard. | ||||
.Pp | |||||
The | |||||
.Fn aio_writev | |||||
system call is a FreeBSD extension, and should not be used in portable code. | |||||
.Sh HISTORY | .Sh HISTORY | ||||
The | The | ||||
.Fn aio_write | .Fn aio_write | ||||
system call first appeared in | system call first appeared in | ||||
.Fx 3.0 . | .Fx 3.0 . | ||||
The | |||||
.Fn aio_writev | |||||
system call first appeared in | |||||
.Fx 13.0 . | |||||
.Sh AUTHORS | .Sh AUTHORS | ||||
This manual page was written by | This manual page was written by | ||||
.An Wes Peters Aq Mt wes@softweyr.com . | .An Wes Peters Aq Mt wes@softweyr.com . | ||||
.Sh BUGS | .Sh BUGS | ||||
Invalid information in | Invalid information in | ||||
.Fa iocb->_aiocb_private | .Fa iocb->_aiocb_private | ||||
may confuse the kernel. | may confuse the kernel. |