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