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