io_submit(2)

✨ io_submit(2) ✨ — the Linux syscall manual, but make it make sense 💖

okay bestie, sit down, hydrate, and let's talk about io_submit(2) — that's the syscall page from the Linux man-pages, and yes it's giving "kernel internals" but honestly? it's iconic. 🦋

---

🌸 NAME 🌸

io_submit — submit asynchronous I/O blocks for processing. that's it, that's the whole vibe. you hand the kernel a pile of I/O requests and it goes "bet, I'll get to those." 💅

📚 LIBRARY 📚

Standard C library (libc, -lc). the basics, no cap.

🎀 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]);

yes it's the raw syscall(2) route. we'll talk about the glow-up version in VERSIONS, don't worry. 🙈

💖 DESCRIPTION 💖

not me about to say the most important thing first: you probably want to use the io_setup(3) wrapper function provided by libaio instead. see VERSIONS for the tea. 🍓

the actual tea ☕

io_submit() queues up 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, and those bad boys get submitted to context ctx_id. it's giving "batch submit, no small talk." ✨

the iocb structure 👑

the iocb (I/O control block) structure, defined over in linux/aio_abi.h, is literally the blueprint — it defines the parameters that control the I/O operation. main character energy fr fr.

#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, one by one 🧚

• aio_data — this data gets copied into the data field of the io_event structure when the I/O completes (peep io_getevents(2)). it's your little note-to-self that comes back to you. 🫶
• aio_key — internal kernel field. do NOT modify this field after an io_submit() call. hands off, bestie, that one's not yours. 🚫
• aio_rw_flags — this defines the R/W flags passed with the structure. the valid values are:
  • RWF_APPEND (since Linux 4.16) — append data to the end of the file. check the description of the flag with the same name in pwritev2(2), plus the O_APPEND description in open(2). the aio_offset field is ignored, and the file offset is not changed. no cap.
  • RWF_DSYNC (since Linux 4.13) — write operation completes according to the requirement of synchronized I/O data integrity. see the same-name flag in pwritev2(2) and the O_DSYNC bit in open(2).
  • RWF_HIPRI (since Linux 4.13) — high priority request, poll if possible. VIP treatment, literally. 👑
  • RWF_NOWAIT (since Linux 4.14) — don't wait if the I/O will block for operations like file block allocations, dirty page flush, mutex locks, or a congested block device inside the kernel. if any of those 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)). it's the "I'm not waiting in line" flag. 💅
  • RWF_SYNC (since Linux 4.13) — write operation completes according to the requirement of synchronized I/O file integrity. see the same-name flag in pwritev2(2) and the O_SYNC description in open(2).
  • RWF_NOAPPEND (since Linux 6.9) — do not honor the O_APPEND open(2) flag. see the RWF_NOAPPEND description 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 RWF_ATOMIC description in pwritev2(2). for usage with IOCB_CMD_PWRITEV, the upper vector limit is stx_atomic_write_segments_max — check the STATX_WRITE_ATOMIC and stx_atomic_write_segments_max descriptions in statx(2). atomicity is the moment. 🔥
• aio_lio_opcode — this defines the type of I/O to be performed by the iocb structure. the valid values come from 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. it's a little "ding! done 💌" notification.
  • 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 — and heads up, that number may be less than n, or 0 if n is zero. so yeah, partial submissions are a real thing, it's not lying to you. 😭

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

💀 ERRORS 💀

• EAGAIN — insufficient resources are available to queue any iocbs. the queue said "we're full bestie." 🫠
• 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. (this arch said "not my problem.") 🙈
• 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. permission check said no. 🚫

🌈 VERSIONS 🌈

libaio provides a wrapper function with the same name, but a different prototype and return value. you probably want to use that wrapper. (this is me, gently, taking your hand and steering you toward the wrapper.) 🫶

📜 STANDARDS 📜

Linux.

🦋 HISTORY 🦋

Linux 2.5. vintage, honestly.

👀 SEE ALSO 👀

io_cancel(2), io_destroy(2), io_getevents(2), io_setup(2), io_submit(3), aio(7)

---

and that's the page, bestie!! 🎀 this little writeup came from Linux man-pages 6.20, dated 2026-04-11 — so if the kernel did a glow-up since then, that's between you and the source tree. go submit some I/O, you're doing amazing, periodt. 💅✨