xref: /freebsd/lib/libsys/lio_listio.2 (revision 8e1f58caf79bd50e6d0b1ae29d4fee8344f6f84c) 
1.\" Copyright (c) 2003 Tim J. Robbins
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 THE AUTHOR 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 THE AUTHOR 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 August 22, 2021
26.Dt LIO_LISTIO 2
27.Os
28.Sh NAME
29.Nm lio_listio
30.Nd "list directed I/O (REALTIME)"
31.Sh LIBRARY
32.Lb libc
33.Sh SYNOPSIS
34.In aio.h
35.Ft int
36.Fo lio_listio
37.Fa "int mode"
38.Fa "struct aiocb * const list[]"
39.Fa "int nent"
40.Fa "struct sigevent *sig"
41.Fc
42.Sh DESCRIPTION
43The
44.Fn lio_listio
45function initiates a list of I/O requests with a single function call.
46The
47.Fa list
48argument is an array of pointers to
49.Vt aiocb
50structures describing each operation to perform,
51with
52.Fa nent
53elements.
54.Dv NULL
55elements are ignored.
56.Pp
57The
58.Va aio_lio_opcode
59field of each
60.Vt aiocb
61specifies the operation to be performed.
62The following operations are supported:
63.Bl -tag -width ".Dv LIO_WRITE"
64.It Dv LIO_READ
65Read data as if by a call to
66.Xr aio_read 2 .
67.It Dv LIO_READV
68Read data as if by a call to
69.Xr aio_readv 2 .
70.It Dv LIO_NOP
71No operation.
72.It Dv LIO_WRITE
73Write data as if by a call to
74.Xr aio_write 2 .
75.It Dv LIO_WRITEV
76Write data as if by a call to
77.Xr aio_writev 2 .
78.El
79.Pp
80If the
81.Fa mode
82argument is
83.Dv LIO_WAIT ,
84.Fn lio_listio
85does not return until all the requested operations have been completed.
86If
87.Fa mode
88is
89.Dv LIO_NOWAIT ,
90.Fa sig
91can be used to request asynchronous notification when all operations have
92completed.
93If
94.Fa sig
95is
96.Dv NULL ,
97no notification is sent.
98.Pp
99For
100.Dv SIGEV_KEVENT
101notifications,
102the posted kevent will contain:
103.Bl -column ".Va filter"
104.It Sy Member Ta Sy Value
105.It Va ident Ta Fa list
106.It Va filter Ta Dv EVFILT_LIO
107.It Va udata Ta
108value stored in
109.Fa sig->sigev_value
110.El
111.Pp
112For
113.Dv SIGEV_SIGNO
114and
115.Dv SIGEV_THREAD_ID
116notifications,
117the information for the queued signal will include
118.Dv SI_ASYNCIO
119in the
120.Va si_code
121field and the value stored in
122.Fa sig->sigev_value
123in the
124.Va si_value
125field.
126.Pp
127For
128.Dv SIGEV_THREAD
129notifications,
130the value stored in
131.Fa sig->sigev_value
132is passed to the
133.Fa sig->sigev_notify_function
134as described in
135.Xr sigevent 3 .
136.Pp
137The order in which the requests are carried out is not specified;
138in particular, there is no guarantee that they will be executed in
139the order 0, 1, ...,
140.Fa nent Ns \-1 .
141.Sh RETURN VALUES
142If
143.Fa mode
144is
145.Dv LIO_WAIT ,
146the
147.Fn lio_listio
148function returns 0 if the operations completed successfully,
149otherwise \-1.
150.Pp
151If
152.Fa mode
153is
154.Dv LIO_NOWAIT ,
155the
156.Fn lio_listio
157function returns 0 if the operations are successfully queued,
158otherwise \-1.
159.Sh ERRORS
160The
161.Fn lio_listio
162function will fail if:
163.Bl -tag -width Er
164.It Bq Er EAGAIN
165There are not enough resources to enqueue the requests.
166.It Bq Er EAGAIN
167The request would cause the system-wide limit
168.Dv {AIO_MAX}
169to be exceeded.
170.It Bq Er EINVAL
171The
172.Fa mode
173argument is neither
174.Dv LIO_WAIT
175nor
176.Dv LIO_NOWAIT ,
177or
178.Fa nent
179is greater than
180.Dv {AIO_LISTIO_MAX} .
181.It Bq Er EINVAL
182The asynchronous notification method in
183.Fa sig->sigev_notify
184is invalid or not supported.
185.It Bq Er EINTR
186A signal interrupted the system call before it could be completed.
187.It Bq Er EIO
188One or more requests failed.
189.El
190.Pp
191In addition, the
192.Fn lio_listio
193function may fail for any of the reasons listed for
194.Xr aio_read 2
195and
196.Xr aio_write 2 .
197.Pp
198If
199.Fn lio_listio
200succeeds, or fails with an error code of
201.Er EAGAIN , EINTR ,
202or
203.Er EIO ,
204some of the requests may have been initiated.
205The caller should check the error status of each
206.Vt aiocb
207structure individually by calling
208.Xr aio_error 2 .
209.Sh SEE ALSO
210.Xr aio_error 2 ,
211.Xr aio_read 2 ,
212.Xr aio_readv 2 ,
213.Xr aio_write 2 ,
214.Xr aio_writev 2 ,
215.Xr read 2 ,
216.Xr write 2 ,
217.Xr sigevent 3 ,
218.Xr siginfo 3 ,
219.Xr aio 4
220.Sh STANDARDS
221The
222.Fn lio_listio
223function is expected to conform to
224.St -p1003.1-2001 .
225The
226.Dv LIO_READV
227and
228.Dv LIO_WRITEV
229operations are
230.Fx extensions, and should not be used in portable code.
231.Sh HISTORY
232The
233.Fn lio_listio
234system call first appeared in
235.Fx 3.0 .
236