www.LinuxHowtos.org howtos, tips&tricks and tutorials for linux

from small one page howto to huge articles all in one place

Other .linuxhowtos.org sites:gentoo.linuxhowtos.org

Last additions:

using iotop to find disk usage hogs

words:

887

views:

215266

userrating:

May 25th. 2007:

Words

486

Views

261796

why adblockers are bad

Workaround and fixes for the current Core Dump Handling vulnerability affected kernels

words:

161

views:

154026

userrating:

April, 26th. 2006:

Words

Views

110057

New subdomain: toolsntoys.linuxhowtos.org

You are here: manpages

io_submit

Section: System Calls (2)
Updated: 202-0-11
Index Return to Main Contents

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.