bionic (3) lio_listio.3posix.gz

Provided by: manpages-posix-dev_2013a-2_all bug

PROLOG

       This  manual  page  is part of the POSIX Programmer's Manual.  The Linux implementation of this interface
       may differ (consult the corresponding Linux manual page for details of Linux behavior), or the  interface
       may not be implemented on Linux.

NAME

       lio_listio — list directed I/O

SYNOPSIS

       #include <aio.h>

       int lio_listio(int mode, struct aiocb *restrict const list[restrict],
           int nent, struct sigevent *restrict sig);

DESCRIPTION

       The lio_listio() function shall initiate a list of I/O requests with a single function call.

       The  mode  argument  takes  one  of  the values LIO_WAIT or LIO_NOWAIT declared in <aio.h> and determines
       whether the function returns when the I/O operations have been completed, or as soon  as  the  operations
       have been queued. If the mode argument is LIO_WAIT, the function shall wait until all I/O is complete and
       the sig argument shall be ignored.

       If the mode argument is LIO_NOWAIT, the function shall return immediately, and asynchronous  notification
       shall occur, according to the sig argument, when all the I/O operations complete. If sig is NULL, then no
       asynchronous notification shall occur. If sig is not NULL, asynchronous notification occurs as  specified
       in Section 2.4.1, Signal Generation and Delivery when all the requests in list have completed.

       The I/O requests enumerated by list are submitted in an unspecified order.

       The  list  argument  is  an  array of pointers to aiocb structures. The array contains nent elements. The
       array may contain NULL elements, which shall be ignored.

       If the buffer pointed to by list or the aiocb structures pointed to by the elements  of  the  array  list
       become  illegal  addresses  before  all asynchronous I/O completed and, if necessary, the notification is
       sent, then the behavior is undefined. If the buffers pointed to  by  the  aio_buf  member  of  the  aiocb
       structure pointed to by the elements of the array list become illegal addresses prior to the asynchronous
       I/O associated with that aiocb structure being completed, the behavior is undefined.

       The aio_lio_opcode field of each aiocb structure specifies the operation to be performed.  The  supported
       operations  are  LIO_READ,  LIO_WRITE,  and  LIO_NOP;  these symbols are defined in <aio.h>.  The LIO_NOP
       operation causes the list entry to be ignored. If the aio_lio_opcode element is equal to  LIO_READ,  then
       an  I/O  operation is submitted as if by a call to aio_read() with the aiocbp equal to the address of the
       aiocb structure. If the aio_lio_opcode element is equal to LIO_WRITE, then an I/O operation is  submitted
       as if by a call to aio_write() with the aiocbp equal to the address of the aiocb structure.

       The aio_fildes member specifies the file descriptor on which the operation is to be performed.

       The aio_buf member specifies the address of the buffer to or from which the data is transferred.

       The aio_nbytes member specifies the number of bytes of data to be transferred.

       The  members  of  the  aiocb  structure  further  describe the I/O operation to be performed, in a manner
       identical to that of the corresponding aiocb structure  when  used  by  the  aio_read()  and  aio_write()
       functions.

       The nent argument specifies how many elements are members of the list; that is, the length of the array.

       The  behavior of this function is altered according to the definitions of synchronized I/O data integrity
       completion and synchronized I/O file integrity completion if synchronized I/O  is  enabled  on  the  file
       associated with aio_fildes.

       For  regular  files,  no  data  transfer shall occur past the offset maximum established in the open file
       description associated with aiocbp->aio_fildes.

       If sig->sigev_notify is SIGEV_THREAD and sig->sigev_notify_attributes is a non-null pointer and the block
       pointed to by this pointer becomes an illegal address prior to all asynchronous I/O being completed, then
       the behavior is undefined.

RETURN VALUE

       If the mode argument has the value LIO_NOWAIT, the lio_listio() function shall return the value  zero  if
       the  I/O  operations  are  successfully queued; otherwise, the function shall return the value −1 and set
       errno to indicate the error.

       If the mode argument has the value LIO_WAIT, the lio_listio() function shall return the value  zero  when
       all  the indicated I/O has completed successfully. Otherwise, lio_listio() shall return a value of −1 and
       set errno to indicate the error.

       In either case, the return value only indicates the success or failure of the lio_listio()  call  itself,
       not the status of the individual I/O requests. In some cases one or more of the I/O requests contained in
       the list may fail.  Failure of an individual request does not prevent completion of any other  individual
       request.  To  determine  the  outcome of each I/O request, the application shall examine the error status
       associated with each aiocb control block. The error statuses so returned are identical to those  returned
       as the result of an aio_read() or aio_write() function.

ERRORS

       The lio_listio() function shall fail if:

       EAGAIN The  resources  necessary  to  queue  all the I/O requests were not available. The application may
              check the error status for each aiocb to determine the individual request(s) that failed.

       EAGAIN The number of entries indicated by  nent  would  cause  the  system-wide  limit  {AIO_MAX}  to  be
              exceeded.

       EINVAL The mode argument is not a proper value, or the value of nent was greater than {AIO_LISTIO_MAX}.

       EINTR  A  signal  was  delivered  while  waiting  for  all  I/O  requests  to complete during an LIO_WAIT
              operation. Note that, since each I/O operation invoked by  lio_listio()  may  possibly  provoke  a
              signal  when  it  completes, this error return may be caused by the completion of one (or more) of
              the very I/O operations being  awaited.  Outstanding  I/O  requests  are  not  canceled,  and  the
              application  shall  examine  each  list  element  to  determine whether the request was initiated,
              canceled, or completed.

       EIO    One or more of the individual I/O operations failed. The application may check  the  error  status
              for each aiocb structure to determine the individual request(s) that failed.

       In addition to the errors returned by the lio_listio() function, if the lio_listio() function succeeds or
       fails with errors of [EAGAIN], [EINTR], or [EIO], then some of the I/O specified by  the  list  may  have
       been  initiated.  If  the lio_listio() function fails with an error code other than [EAGAIN], [EINTR], or
       [EIO], no operations from the list shall have been initiated. The I/O operation indicated  by  each  list
       element  can  encounter errors specific to the individual read or write function being performed. In this
       event, the error status for each aiocb control block contains the associated error code. The error  codes
       that  can  be  set  are  the  same  as  would  be set by a read() or write() function, with the following
       additional error codes possible:

       EAGAIN The requested I/O operation was not queued due to resource limitations.

       ECANCELED
              The requested I/O was canceled before the I/O completed due to an explicit aio_cancel() request.

       EFBIG  The aiocbp->aio_lio_opcode is LIO_WRITE, the file is a regular file, aiocbp->aio_nbytes is greater
              than 0, and the aiocbp->aio_offset is greater than or equal to the offset maximum in the open file
              description associated with aiocbp->aio_fildes.

       EINPROGRESS
              The requested I/O is in progress.

       EOVERFLOW
              The aiocbp->aio_lio_opcode is LIO_READ, the file is a regular file, aiocbp->aio_nbytes is  greater
              than  0,  and the aiocbp->aio_offset is before the end-of-file and is greater than or equal to the
              offset maximum in the open file description associated with aiocbp->aio_fildes.

       The following sections are informative.

EXAMPLES

       None.

APPLICATION USAGE

       None.

RATIONALE

       Although it may appear that there are inconsistencies in the specified circumstances for error codes, the
       [EIO]  error  condition  applies  when  any  circumstance  relating to an individual operation makes that
       operation fail. This might be due to a badly formulated request (for example, the aio_lio_opcode field is
       invalid,  and  aio_error()  returns  [EINVAL]) or might arise from application behavior (for example, the
       file descriptor is closed before the operation is initiated, and aio_error() returns [EBADF]).

       The limitation on the set of error codes returned when operations from the list shall have been initiated
       enables  applications  to  know  when operations have been started and whether aio_error() is valid for a
       specific operation.

FUTURE DIRECTIONS

       None.

SEE ALSO

       aio_read(), aio_write(), aio_error(), aio_return(), aio_cancel(), close(), exec, exit(), fork(), lseek(),
       read()

       The Base Definitions volume of POSIX.1‐2008, <aio.h>

       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2013 Edition,
       Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open  Group  Base
       Specifications  Issue 7, Copyright (C) 2013 by the Institute of Electrical and Electronics Engineers, Inc
       and The Open Group.  (This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In  the  event
       of  any  discrepancy between this version and the original IEEE and The Open Group Standard, the original
       IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at
       http://www.unix.org/online.html .

       Any  typographical  or formatting errors that appear in this page are most likely to have been introduced
       during  the  conversion  of  the  source  files  to  man  page  format.  To  report  such   errors,   see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .