xref: /freebsd/lib/libsys/lio_listio.2 (revision e2257b31) 
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 January 13, 2024
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.Dv LIO_READ ,
82.Dv LIO_READV ,
83.Dv LIO_WRITE ,
84.Dv LIO_WRITEV
85opcodes are or-ed with the
86.Dv LIO_FOFFSET
87flag, the corresponding read or write operation uses the current file
88descriptor offset instead of
89.Va aio_offset
90from
91.Vt aiocb .
92.Pp
93If the
94.Fa mode
95argument is
96.Dv LIO_WAIT ,
97.Fn lio_listio
98does not return until all the requested operations have been completed.
99If
100.Fa mode
101is
102.Dv LIO_NOWAIT ,
103.Fa sig
104can be used to request asynchronous notification when all operations have
105completed.
106If
107.Fa sig
108is
109.Dv NULL ,
110no notification is sent.
111.Pp
112For
113.Dv SIGEV_KEVENT
114notifications,
115the posted kevent will contain:
116.Bl -column ".Va filter"
117.It Sy Member Ta Sy Value
118.It Va ident Ta Fa list
119.It Va filter Ta Dv EVFILT_LIO
120.It Va udata Ta
121value stored in
122.Fa sig->sigev_value
123.El
124.Pp
125For
126.Dv SIGEV_SIGNO
127and
128.Dv SIGEV_THREAD_ID
129notifications,
130the information for the queued signal will include
131.Dv SI_ASYNCIO
132in the
133.Va si_code
134field and the value stored in
135.Fa sig->sigev_value
136in the
137.Va si_value
138field.
139.Pp
140For
141.Dv SIGEV_THREAD
142notifications,
143the value stored in
144.Fa sig->sigev_value
145is passed to the
146.Fa sig->sigev_notify_function
147as described in
148.Xr sigevent 3 .
149.Pp
150The order in which the requests are carried out is not specified;
151in particular, there is no guarantee that they will be executed in
152the order 0, 1, ...,
153.Fa nent Ns \-1 .
154.Sh RETURN VALUES
155If
156.Fa mode
157is
158.Dv LIO_WAIT ,
159the
160.Fn lio_listio
161function returns 0 if the operations completed successfully,
162otherwise \-1.
163.Pp
164If
165.Fa mode
166is
167.Dv LIO_NOWAIT ,
168the
169.Fn lio_listio
170function returns 0 if the operations are successfully queued,
171otherwise \-1.
172.Sh ERRORS
173The
174.Fn lio_listio
175function will fail if:
176.Bl -tag -width Er
177.It Bq Er EAGAIN
178There are not enough resources to enqueue the requests.
179.It Bq Er EAGAIN
180The request would cause the system-wide limit
181.Dv {AIO_MAX}
182to be exceeded.
183.It Bq Er EINVAL
184The
185.Fa mode
186argument is neither
187.Dv LIO_WAIT
188nor
189.Dv LIO_NOWAIT ,
190or
191.Fa nent
192is greater than
193.Dv {AIO_LISTIO_MAX} .
194.It Bq Er EINVAL
195The asynchronous notification method in
196.Fa sig->sigev_notify
197is invalid or not supported.
198.It Bq Er EINTR
199A signal interrupted the system call before it could be completed.
200.It Bq Er EIO
201One or more requests failed.
202.El
203.Pp
204In addition, the
205.Fn lio_listio
206function may fail for any of the reasons listed for
207.Xr aio_read 2
208and
209.Xr aio_write 2 .
210.Pp
211If
212.Fn lio_listio
213succeeds, or fails with an error code of
214.Er EAGAIN , EINTR ,
215or
216.Er EIO ,
217some of the requests may have been initiated.
218The caller should check the error status of each
219.Vt aiocb
220structure individually by calling
221.Xr aio_error 2 .
222.Sh SEE ALSO
223.Xr aio_error 2 ,
224.Xr aio_read 2 ,
225.Xr aio_readv 2 ,
226.Xr aio_write 2 ,
227.Xr aio_writev 2 ,
228.Xr read 2 ,
229.Xr write 2 ,
230.Xr sigevent 3 ,
231.Xr siginfo 3 ,
232.Xr aio 4
233.Sh STANDARDS
234The
235.Fn lio_listio
236function is expected to conform to
237.St -p1003.1-2001 .
238The
239.Dv LIO_READV
240and
241.Dv LIO_WRITEV
242operations are
243.Fx extensions, and should not be used in portable code.
244.Sh HISTORY
245The
246.Fn lio_listio
247system call first appeared in
248.Fx 3.0 .
249