LIO_LISTIO(3)              POSIX Programmer's Manual             LIO_LISTIO(3)



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

NNAAMMEE
       lio_listio -- list directed I/O

SSYYNNOOPPSSIISS
       #include <aio.h>

       int lio_listio(int _m_o_d_e, struct aiocb *restrict const _l_i_s_t[restrict],
           int _n_e_n_t, struct sigevent *restrict _s_i_g);

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

       The _m_o_d_e argument takes one of the values LIO_WAIT or LIO_NOWAIT
       declared in _<_a_i_o_._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 _m_o_d_e argument is LIO_WAIT, the function shall
       wait until all I/O is complete and the _s_i_g argument shall be ignored.

       If the _m_o_d_e argument is LIO_NOWAIT, the function shall return
       immediately, and asynchronous notification shall occur, according to
       the _s_i_g argument, when all the I/O operations complete. If _s_i_g is NULL,
       then no asynchronous notification shall occur. If _s_i_g is not NULL,
       asynchronous notification occurs as specified in _S_e_c_t_i_o_n _2_._4_._1, _S_i_g_n_a_l
       _G_e_n_e_r_a_t_i_o_n _a_n_d _D_e_l_i_v_e_r_y when all the requests in _l_i_s_t have completed.

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

       The _l_i_s_t argument is an array of pointers to aaiiooccbb structures. The
       array contains _n_e_n_t elements. The array may contain NULL elements,
       which shall be ignored.

       If the buffer pointed to by _l_i_s_t or the aaiiooccbb structures pointed to by
       the elements of the array _l_i_s_t 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
       _a_i_o___b_u_f member of the aaiiooccbb structure pointed to by the elements of the
       array _l_i_s_t become illegal addresses prior to the asynchronous I/O
       associated with that aaiiooccbb structure being completed, the behavior is
       undefined.

       The _a_i_o___l_i_o___o_p_c_o_d_e field of each aaiiooccbb structure specifies the
       operation to be performed. The supported operations are LIO_READ,
       LIO_WRITE, and LIO_NOP; these symbols are defined in _<_a_i_o_._h_>.  The
       LIO_NOP operation causes the list entry to be ignored. If the
       _a_i_o___l_i_o___o_p_c_o_d_e element is equal to LIO_READ, then an I/O operation is
       submitted as if by a call to _a_i_o___r_e_a_d() with the _a_i_o_c_b_p equal to the
       address of the aaiiooccbb structure. If the _a_i_o___l_i_o___o_p_c_o_d_e element is equal
       to LIO_WRITE, then an I/O operation is submitted as if by a call to
       _a_i_o___w_r_i_t_e() with the _a_i_o_c_b_p equal to the address of the aaiiooccbb
       structure.

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

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

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

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

       The _n_e_n_t 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 _a_i_o___f_i_l_d_e_s.

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

       If _s_i_g->_s_i_g_e_v___n_o_t_i_f_y is SIGEV_THREAD and _s_i_g->_s_i_g_e_v___n_o_t_i_f_y___a_t_t_r_i_b_u_t_e_s
       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.

RREETTUURRNN VVAALLUUEE
       If the _m_o_d_e argument has the value LIO_NOWAIT, the _l_i_o___l_i_s_t_i_o()
       function shall return the value zero if the I/O operations are
       successfully queued; otherwise, the function shall return the value -1
       and set _e_r_r_n_o to indicate the error.

       If the _m_o_d_e argument has the value LIO_WAIT, the _l_i_o___l_i_s_t_i_o() function
       shall return the value zero when all the indicated I/O has completed
       successfully. Otherwise, _l_i_o___l_i_s_t_i_o() shall return a value of -1 and
       set _e_r_r_n_o to indicate the error.

       In either case, the return value only indicates the success or failure
       of the _l_i_o___l_i_s_t_i_o() 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 aaiiooccbb control block. The error statuses so
       returned are identical to those returned as the result of an _a_i_o___r_e_a_d()
       or _a_i_o___w_r_i_t_e() function.

EERRRROORRSS
       The _l_i_o___l_i_s_t_i_o() function shall fail if:

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

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

       EEIINNVVAALL The _m_o_d_e argument is not a proper value, or the value of _n_e_n_t
              was greater than {AIO_LISTIO_MAX}.

       EEIINNTTRR  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 _l_i_o___l_i_s_t_i_o() 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.

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

       In addition to the errors returned by the _l_i_o___l_i_s_t_i_o() function, if the
       _l_i_o___l_i_s_t_i_o() function succeeds or fails with errors of [[EEAAGGAAIINN]],
       [[EEIINNTTRR]], or [[EEIIOO]], then some of the I/O specified by the list may have
       been initiated. If the _l_i_o___l_i_s_t_i_o() function fails with an error code
       other than [[EEAAGGAAIINN]], [[EEIINNTTRR]], or [[EEIIOO]], 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
       aaiiooccbb control block contains the associated error code. The error codes
       that can be set are the same as would be set by a _r_e_a_d() or _w_r_i_t_e()
       function, with the following additional error codes possible:

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

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

       EEFFBBIIGG  The _a_i_o_c_b_p->_a_i_o___l_i_o___o_p_c_o_d_e is LIO_WRITE, the file is a regular
              file, _a_i_o_c_b_p->_a_i_o___n_b_y_t_e_s is greater than 0, and the
              _a_i_o_c_b_p->_a_i_o___o_f_f_s_e_t is greater than or equal to the offset
              maximum in the open file description associated with
              _a_i_o_c_b_p->_a_i_o___f_i_l_d_e_s.

       EEIINNPPRROOGGRREESSSS
              The requested I/O is in progress.

       EEOOVVEERRFFLLOOWW
              The _a_i_o_c_b_p->_a_i_o___l_i_o___o_p_c_o_d_e is LIO_READ, the file is a regular
              file, _a_i_o_c_b_p->_a_i_o___n_b_y_t_e_s is greater than 0, and the
              _a_i_o_c_b_p->_a_i_o___o_f_f_s_e_t is before the end-of-file and is greater than
              or equal to the offset maximum in the open file description
              associated with _a_i_o_c_b_p->_a_i_o___f_i_l_d_e_s.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
       None.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       None.

RRAATTIIOONNAALLEE
       Although it may appear that there are inconsistencies in the specified
       circumstances for error codes, the [[EEIIOO]] 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 _a_i_o___l_i_o___o_p_c_o_d_e field is invalid, and _a_i_o___e_r_r_o_r() returns
       [[EEIINNVVAALL]]) or might arise from application behavior (for example, the
       file descriptor is closed before the operation is initiated, and
       _a_i_o___e_r_r_o_r() returns [[EEBBAADDFF]]).

       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 _a_i_o___e_r_r_o_r() is valid for a
       specific operation.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _a_i_o___r_e_a_d(), _a_i_o___w_r_i_t_e(), _a_i_o___e_r_r_o_r(), _a_i_o___r_e_t_u_r_n(), _a_i_o___c_a_n_c_e_l(),
       _c_l_o_s_e(), _e_x_e_c, _e_x_i_t(), _f_o_r_k(), _l_s_e_e_k(), _r_e_a_d()

       The Base Definitions volume of POSIX.1-2017, <<aaiioo..hh>>

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1-2017, Standard for Information Technology --
       Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the
       Institute of Electrical and Electronics Engineers, Inc and The Open
       Group.  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.opengroup.org/unix/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 .



IEEE/The Open Group                  2017                        LIO_LISTIO(3)
