1.\" $NetBSD: lio_listio.3,v 1.5 2011/08/12 23:40:43 wiz Exp $ 2.\" 3.\" Copyright (c) 2003 Tim J. Robbins 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.\" $FreeBSD: /repoman/r/ncvs/src/lib/libc/sys/lio_listio.2,v 1.6 2006/10/07 05:13:32 trhodes Exp $ 28.\" 29.Dd August 12, 2011 30.Dt LIO_LISTIO 3 31.Os 32.Sh NAME 33.Nm lio_listio 34.Nd list directed I/O (REALTIME) 35.Sh LIBRARY 36.Lb librt 37.Sh SYNOPSIS 38.In aio.h 39.Ft int 40.Fo lio_listio 41.Fa "int mode" 42.Fa "struct aiocb * const list[]" 43.Fa "int nent" 44.Fa "struct sigevent *sig" 45.Fc 46.Sh DESCRIPTION 47The 48.Fn lio_listio 49function initiates a list of I/O requests with a single function call. 50The 51.Fa list 52argument is an array of pointers to 53.Vt aiocb 54structures describing each operation to perform, 55with 56.Fa nent 57elements. 58.Dv NULL 59elements are ignored. 60.Pp 61The 62.Va aio_lio_opcode 63field of each 64.Vt aiocb 65specifies the operation to be performed. 66The following operations are supported: 67.Bl -tag -width ".Dv LIO_WRITE" -offset indent 68.It Dv LIO_READ 69Read data as if by a call to 70.Xr aio_read 3 . 71.It Dv LIO_NOP 72No operation. 73.It Dv LIO_WRITE 74Write data as if by a call to 75.Xr aio_write 3 . 76.El 77.Pp 78If the 79.Fa mode 80argument is 81.Dv LIO_WAIT , 82.Fn lio_listio 83does not return until all the requested operations have been completed. 84If 85.Fa mode 86is 87.Dv LIO_NOWAIT , 88the requests are processed asynchronously, and the signal specified by 89.Fa sig 90is sent when all operations have completed. 91If 92.Fa sig 93is 94.Dv NULL , 95the calling process is not notified of I/O completion. 96.Pp 97The order in which the requests are carried out is not specified, 98and there is no guarantee that they will be executed sequentially. 99.Sh RETURN VALUES 100If 101.Fa mode 102is 103.Dv LIO_WAIT , 104the 105.Fn lio_listio 106function returns 0 if the operations completed successfully, 107otherwise \-1. 108.Pp 109If 110.Fa mode 111is 112.Dv LIO_NOWAIT , 113the 114.Fn lio_listio 115function returns 0 if the operations are successfully queued, 116otherwise \-1. 117.Sh ERRORS 118The 119.Fn lio_listio 120function will fail if: 121.Bl -tag -width Er 122.It Bq Er EAGAIN 123There are not enough resources to enqueue the requests; or 124the request would cause the system-wide limit 125.Dv AIO_MAX 126to be exceeded. 127.It Bq Er EINTR 128A signal interrupted the system call before it could be completed. 129.It Bq Er EINVAL 130The 131.Fa mode 132argument is neither 133.Dv LIO_WAIT 134nor 135.Dv LIO_NOWAIT , 136or 137.Fa nent 138is greater than 139.Dv AIO_LISTIO_MAX . 140.It Bq Er EIO 141One or more requests failed. 142.El 143.Pp 144In addition, the 145.Fn lio_listio 146function may fail for any of the reasons listed for 147.Xr aio_read 3 148and 149.Xr aio_write 3 . 150.Pp 151If 152.Fn lio_listio 153succeeds, or fails with an error code of 154.Er EAGAIN , EINTR , 155or 156.Er EIO , 157some of the requests may have been initiated. 158The caller should check the error status of each 159.Vt aiocb 160structure individually by calling 161.Xr aio_error 3 . 162.Sh SEE ALSO 163.Xr read 2 , 164.Xr siginfo 2 , 165.Xr write 2 , 166.Xr aio 3 , 167.Xr sigevent 3 168.Sh STANDARDS 169The 170.Fn lio_listio 171function is expected to conform to 172.St -p1003.1-2001 . 173