| .\" Copyright (C) 2010, Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" |
| .\" %%%LICENSE_START(GPLv2+_DOC_FULL) |
| .\" This is free documentation; you can redistribute it and/or |
| .\" modify it under the terms of the GNU General Public License as |
| .\" published by the Free Software Foundation; either version 2 of |
| .\" the License, or (at your option) any later version. |
| .\" |
| .\" The GNU General Public License's references to "object code" |
| .\" and "executables" are to be interpreted as the output of any |
| .\" document formatting or typesetting system, including |
| .\" intermediate and printed output. |
| .\" |
| .\" This manual is distributed in the hope that it will be useful, |
| .\" but WITHOUT ANY WARRANTY; without even the implied warranty of |
| .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| .\" GNU General Public License for more details. |
| .\" |
| .\" You should have received a copy of the GNU General Public |
| .\" License along with this manual; if not, see |
| .\" <http://www.gnu.org/licenses/>. |
| .\" %%%LICENSE_END |
| .\" |
| .TH LIO_LISTIO 3 2021-03-22 "" "Linux Programmer's Manual" |
| .SH NAME |
| lio_listio \- initiate a list of I/O requests |
| .SH SYNOPSIS |
| .nf |
| .B "#include <aio.h>" |
| .PP |
| .BI "int lio_listio(int " mode ", struct aiocb *restrict const " aiocb_list [restrict], |
| .BI " int " nitems ", struct sigevent *restrict " sevp ); |
| .PP |
| Link with \fI\-lrt\fP. |
| .fi |
| .SH DESCRIPTION |
| The |
| .BR lio_listio () |
| function initiates the list of I/O operations described by the array |
| .IR aiocb_list . |
| .PP |
| The |
| .I mode |
| operation has one of the following values: |
| .TP |
| .B LIO_WAIT |
| The call blocks until all operations are complete. |
| The |
| .I sevp |
| argument is ignored. |
| .TP |
| .B LIO_NOWAIT |
| The I/O operations are queued for processing and the call returns immediately. |
| When all of the I/O operations complete, asynchronous notification occurs, |
| as specified by the |
| .IR sevp |
| argument; see |
| .BR sigevent (7) |
| for details. |
| If |
| .IR sevp |
| is NULL, no asynchronous notification occurs. |
| .PP |
| The |
| .I aiocb_list |
| argument is an array of pointers to |
| .I aiocb |
| structures that describe I/O operations. |
| These operations are executed in an unspecified order. |
| The |
| .I nitems |
| argument specifies the size of the array |
| .IR aiocb_list . |
| Null pointers in |
| .I aiocb_list |
| are ignored. |
| .PP |
| In each control block in |
| .IR aiocb_list , |
| the |
| .I aio_lio_opcode |
| field specifies the I/O operation to be initiated, as follows: |
| .TP |
| .BR LIO_READ |
| Initiate a read operation. |
| The operation is queued as for a call to |
| .BR aio_read (3) |
| specifying this control block. |
| .TP |
| .BR LIO_WRITE |
| Initiate a write operation. |
| The operation is queued as for a call to |
| .BR aio_write (3) |
| specifying this control block. |
| .TP |
| .BR LIO_NOP |
| Ignore this control block. |
| .PP |
| The remaining fields in each control block have the same meanings as for |
| .BR aio_read (3) |
| and |
| .BR aio_write (3). |
| The |
| .I aio_sigevent |
| fields of each control block can be used to specify notifications |
| for the individual I/O operations (see |
| .BR sigevent (7)). |
| .SH RETURN VALUE |
| If |
| .I mode |
| is |
| .BR LIO_NOWAIT , |
| .BR lio_listio () |
| returns 0 if all I/O operations are successfully queued. |
| Otherwise, \-1 is returned, and |
| .I errno |
| is set to indicate the error. |
| .PP |
| If |
| .I mode |
| is |
| .BR LIO_WAIT , |
| .BR lio_listio () |
| returns 0 when all of the I/O operations have completed successfully. |
| Otherwise, \-1 is returned, and |
| .I errno |
| is set to indicate the error. |
| .PP |
| The return status from |
| .BR lio_listio () |
| provides information only about the call itself, |
| not about the individual I/O operations. |
| One or more of the I/O operations may fail, |
| but this does not prevent other operations completing. |
| The status of individual I/O operations in |
| .IR aiocb_list |
| can be determined using |
| .BR aio_error (3). |
| When an operation has completed, |
| its return status can be obtained using |
| .BR aio_return (3). |
| Individual I/O operations can fail for the reasons described in |
| .BR aio_read (3) |
| and |
| .BR aio_write (3). |
| .SH ERRORS |
| The |
| .BR lio_listio () |
| function may fail for the following reasons: |
| .TP |
| .B EAGAIN |
| Out of resources. |
| .TP |
| .B EAGAIN |
| .\" Doesn't happen in glibc(?) |
| The number of I/O operations specified by |
| .I nitems |
| would cause the limit |
| .BR AIO_MAX |
| to be exceeded. |
| .TP |
| .B EINTR |
| .I mode |
| was |
| .BR LIO_WAIT |
| and a signal |
| was caught before all I/O operations completed; see |
| .BR signal (7). |
| (This may even be one of the signals used for |
| asynchronous I/O completion notification.) |
| .TP |
| .B EINVAL |
| .I mode |
| is invalid, or |
| .\" Doesn't happen in glibc(?) |
| .I nitems |
| exceeds the limit |
| .BR AIO_LISTIO_MAX . |
| .TP |
| .B EIO |
| One of more of the operations specified by |
| .IR aiocb_list |
| failed. |
| .\" e.g., ioa_reqprio or aio_lio_opcode was invalid |
| The application can check the status of each operation using |
| .BR aio_return (3). |
| .PP |
| If |
| .BR lio_listio () |
| fails with the error |
| .BR EAGAIN , |
| .BR EINTR , |
| or |
| .BR EIO , |
| then some of the operations in |
| .IR aiocb_list |
| may have been initiated. |
| If |
| .BR lio_listio () |
| fails for any other reason, |
| then none of the I/O operations has been initiated. |
| .SH VERSIONS |
| The |
| .BR lio_listio () |
| function is available since glibc 2.1. |
| .SH ATTRIBUTES |
| For an explanation of the terms used in this section, see |
| .BR attributes (7). |
| .ad l |
| .nh |
| .TS |
| allbox; |
| lbx lb lb |
| l l l. |
| Interface Attribute Value |
| T{ |
| .BR lio_listio () |
| T} Thread safety MT-Safe |
| .TE |
| .hy |
| .ad |
| .sp 1 |
| .SH CONFORMING TO |
| POSIX.1-2001, POSIX.1-2008. |
| .SH NOTES |
| It is a good idea to zero out the control blocks before use. |
| The control blocks must not be changed while the I/O operations |
| are in progress. |
| The buffer areas being read into or written from |
| .\" or the control block of the operation |
| must not be accessed during the operations or undefined results may occur. |
| The memory areas involved must remain valid. |
| .PP |
| Simultaneous I/O operations specifying the same |
| .I aiocb |
| structure produce undefined results. |
| .SH SEE ALSO |
| .BR aio_cancel (3), |
| .BR aio_error (3), |
| .BR aio_fsync (3), |
| .BR aio_return (3), |
| .BR aio_suspend (3), |
| .BR aio_write (3), |
| .BR aio (7) |