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