1.\" $NetBSD: lio_listio.3,v 1.3 2010/05/17 19:22:31 jruoho 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 May 17, 2010 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. 124.It Bq Er EAGAIN 125The request would cause the system-wide limit 126.Dv AIO_MAX 127to be exceeded. 128.It Bq Er EINTR 129A signal interrupted the system call before it could be completed. 130.It Bq Er EINVAL 131The 132.Fa mode 133argument is neither 134.Dv LIO_WAIT 135nor 136.Dv LIO_NOWAIT , 137or 138.Fa nent 139is greater than 140.Dv AIO_LISTIO_MAX . 141.It Bq Er EIO 142One or more requests failed. 143.El 144.Pp 145In addition, the 146.Fn lio_listio 147function may fail for any of the reasons listed for 148.Xr aio_read 3 149and 150.Xr aio_write 3 . 151.Pp 152If 153.Fn lio_listio 154succeeds, or fails with an error code of 155.Er EAGAIN , EINTR , 156or 157.Er EIO , 158some of the requests may have been initiated. 159The caller should check the error status of each 160.Vt aiocb 161structure individually by calling 162.Xr aio_error 3 . 163.Sh SEE ALSO 164.Xr read 2 , 165.Xr siginfo 2 , 166.Xr write 2 , 167.Xr aio 3 168.Sh STANDARDS 169The 170.Fn lio_listio 171function is expected to conform to 172.St -p1003.1-2001 . 173