io_submit(2)

NAME

io_submit - submit asynchronous I/O blocks for processing

LIBRARY

Standard C library (libc, -lc)

SYNOPSIS

#include <linux/aio_abi.h>
#include <sys/syscall.h>    /* Definition of SYS_* constants */
#include <unistd.h>

int syscall(SYS_io_submit, aio_context_t ctx_id, long n, struct iocb *iocbpp[n]);

DESCRIPTION

Note: you probably want to use the io_setup(3) wrapper function provided by libaio; see VERSIONS.

The io_submit() system call queues n I/O request blocks for processing in the AIO context ctx_id. The iocbpp argument should be an array of n 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 iocbs submitted (which may be less than n, or 0 if n is zero).

On error, -1 is returned, and errno is set to indicate the error.

ERRORS

EAGAIN: Insufficient resources are available to queue any iocbs.

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.

EINVAL: n is less than 0.

EINVAL: The iocb at *iocbpp[0] is not properly initialized.

EINVAL: The operation specified is invalid for the file descriptor in the iocb.

EINVAL: 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

libaio ⟨https://pagure.io/libaio⟩ provides a wrapper function with the same name, but different prototype and return value. You probably want to use that wrapper.

STANDARDS

Linux.

HISTORY

Linux 2.5.