# io_submit

## NAME



           io_submit - submit asynchronous I/O blocks for processing
    


## LIBRARY



           Standard C library (_libc_ , _-lc_)
    
           Alternatively, Asynchronous I/O library (_libaio_ , _-laio_); see
           VERSIONS.
    


## SYNOPSIS



           **#include <linux/aio_abi.h>          **/* Defines needed types */
    
           **int io_submit(aio_context_t** _ctx_id_**, long** _nr_**, struct iocb ****_iocbpp_**);**
    
           _Note_ : There is no glibc wrapper for this system call; see
           VERSIONS.
    


## DESCRIPTION



           _Note_ : this page describes the raw Linux system call interface.
           The wrapper function provided by _libaio_ uses a different type for
           the _ctx_id_ argument.  See VERSIONS.
    
           The **io_submit**() system call queues _nr_ I/O request blocks for
           processing in the AIO context _ctx_id_.  The _iocbpp_ argument should
           be an array of _nr_ AIO control blocks, which will be submitted to
           context _ctx_id_.
    
           The _iocb_ (I/O control block) structure defined in _linux/aio_abi.h_
           defines the parameters that control the I/O operation.
    
               #include <linux/aio_abi.h>
    
               struct iocb {
                   __u64   aio_data;
                   __u32   PADDED(aio_key, aio_rw_flags);
                   __u16   aio_lio_opcode;
                   __s16   aio_reqprio;
                   __u32   aio_fildes;
                   __u64   aio_buf;
                   __u64   aio_nbytes;
                   __s64   aio_offset;
                   __u64   aio_reserved2;
                   __u32   aio_flags;
                   __u32   aio_resfd;
               };
    
           The fields of this structure are as follows:
    
           _aio_data_
                  This data is copied into the _data_ field of the _io_event_
                  structure upon I/O completion (see io_getevents(2)).
    
           _aio_key_
                  This is an internal field used by the kernel.  Do not
                  modify this field after an **io_submit**() call.
    
           _aio_rw_flags_
                  This defines the R/W flags passed with structure.  The
                  valid values are:
    
                  **RWF_APPEND**(since Linux 4.16)
                         Append data to the end of the file.  See the
                         description of the flag of the same name in
                         pwritev2(2) as well as the description of **O_APPEND**
                         in open(2).  The _aio_offset_ field is ignored.  The
                         file offset is not changed.
    
                  **RWF_DSYNC**(since Linux 4.13)
                         Write operation complete according to requirement of
                         synchronized I/O data integrity.  See the
                         description of the flag of the same name in
                         pwritev2(2) as well the description of **O_DSYNC** in
                         open(2).
    
                  **RWF_HIPRI**(since Linux 4.13)
                         High priority request, poll if possible
    
                  **RWF_NOWAIT**(since Linux 4.14)
                         Don't wait if the I/O will block for operations such
                         as file block allocations, dirty page flush, mutex
                         locks, or a congested block device inside the
                         kernel.  If any of these conditions are met, the
                         control block is returned immediately with a return
                         value of **-EAGAIN** in the _res_ field of the _io_event_
                         structure (see io_getevents(2)).
    
                  **RWF_SYNC**(since Linux 4.13)
                         Write operation complete according to requirement of
                         synchronized I/O file integrity.  See the
                         description of the flag of the same name in
                         pwritev2(2) as well the description of **O_SYNC** in
                         open(2).
    
                  **RWF_NOAPPEND**(since Linux 6.9)
                         Do not honor **O_APPEND open**(2) flag.  See the
                         description of **RWF_NOAPPEND** in pwritev2(2).
    
                  **RWF_ATOMIC**(since Linux 6.11)
                         Write a block of data such that a write will never
                         be torn from power fail or similar.  See the
                         description of **RWF_ATOMIC** in pwritev2(2).  For usage
                         with **IOCB_CMD_PWRITEV** , the upper vector limit is
                         _stx_atomic_write_segments_max._  See
                         **STATX_WRITE_ATOMIC** and _stx_atomic_write_segments_max_
                         description in statx(2).
    
           _aio_lio_opcode_
                  This defines the type of I/O to be performed by the _iocb_
                  structure.  The valid values are defined by the enum
                  defined in _linux/aio_abi.h_ :
    
                      enum {
                          IOCB_CMD_PREAD = 0,
                          IOCB_CMD_PWRITE = 1,
                          IOCB_CMD_FSYNC = 2,
                          IOCB_CMD_FDSYNC = 3,
                          IOCB_CMD_POLL = 5,
                          IOCB_CMD_NOOP = 6,
                          IOCB_CMD_PREADV = 7,
                          IOCB_CMD_PWRITEV = 8,
                      };
    
           _aio_reqprio_
                  This defines the requests priority.
    
           _aio_fildes_
                  The file descriptor on which the I/O operation is to be
                  performed.
    
           _aio_buf_
                  This is the buffer used to transfer data for a read or
                  write operation.
    
           _aio_nbytes_
                  This is the size of the buffer pointed to by _aio_buf_.
    
           _aio_offset_
                  This is the file offset at which the I/O operation is to be
                  performed.
    
           _aio_flags_
                  This is the set of flags associated with the _iocb_
                  structure.  The valid values are:
    
                  **IOCB_FLAG_RESFD**
                         Asynchronous I/O control must signal the file
                         descriptor mentioned in _aio_resfd_ upon completion.
    
                  **IOCB_FLAG_IOPRIO**(since Linux 4.18)
                         Interpret the _aio_reqprio_ field as an **IOPRIO_VALUE**
                         as defined by _linux/ioprio.h_.
    
           _aio_resfd_
                  The file descriptor to signal in the event of asynchronous
                  I/O completion.
    


## RETURN VALUE



           On success, **io_submit**() returns the number of _iocb_ s submitted
           (which may be less than _nr_ , or 0 if _nr_ is zero).  For the failure
           return, see VERSIONS.
    


## ERRORS



           **EAGAIN** Insufficient resources are available to queue any _iocb_ s.
    
           **EBADF** The file descriptor specified in the first _iocb_ is invalid.
    
           **EFAULT** One of the data structures points to invalid data.
    
           **EINVAL** The AIO context specified by _ctx_id_ is invalid.  _nr_ is less
                  than 0.  The _iocb_ at _*iocbpp[0]_ is not properly
                  initialized, the operation specified is invalid for the
                  file descriptor in the _iocb_ , or the value in the
                  _aio_reqprio_ field is invalid.
    
           **ENOSYS io_submit**() is not implemented on this architecture.
    
           **EPERM** The _aio_reqprio_ field is set with the class
                  **IOPRIO_CLASS_RT** , but the submitting context does not have
                  the **CAP_SYS_ADMIN** capability.
    


## VERSIONS



           glibc does not provide a wrapper for this system call.  You could
           invoke it using syscall(2).  But instead, you probably want to use
           the **io_submit**() wrapper function provided by _libaio_.
    
           Note that the _libaio_ wrapper function uses a different type
           (_io_context_t_) for the _ctx_id_ argument.  Note also that the _libaio_
           wrapper does not follow the usual C library conventions for
           indicating errors: on error it returns a negated error number (the
           negative of one of the values listed in ERRORS).  If the system
           call is invoked via syscall(2), then the return value follows the
           usual conventions for indicating an error: -1, with _errno_ set to a
           (positive) value that indicates the error.
    


## STANDARDS



           Linux.
    


* * *