io_submit(3)

💖 io_submit(3) — Linux AIO 💖

okay bestie, welcome to the io_submit page from the Linux AIO manual. this is the one where you yeet a whole pile of io requests at the kernel at once and hope for the best. let's get into it 🫶

✨ NAME ✨

io_submit — Submit io requests. that's it. that's the vibe. 💅

🌸 SYNOPSIS 🌸

#include <errno.h>

#include <libaio.h>

int io_submit(io_context_t ctx, long nr, struct iocb *iocbs[]);

struct iocb {
     void      *data;
     unsigned  key;
     short          aio_lio_opcode;
     short          aio_reqprio;
     int       aio_fildes;
};

🦋 DESCRIPTION 🦋

so io_submit() submits nr iocbs for processing for a given io context ctx. slay.

the way this works is highkey flexible — you can enqueue an arbitrary number of read and write requests at one time. and the requests? they can all be for the same file, all be for different files, or literally every solution in between. no cap, the range is that wide. 🌈

io_submit() gets the nr requests from the array pointed to by iocbs. and which operation actually happens? that's decided by the aio_lio_opcode member in each element of iocbs. let me break it down bestie:

• if that field is IO_CMD_PREAD, a read operation gets enqueued, similar to a call of io_prep_pread for this element of the array — except that the way the termination is signalled is different, as we will see below. 👀
• if the aio_lio_opcode member is IO_CMD_PWRITE, a write operation gets enqueued.
• otherwise the aio_lio_opcode must be IO_CMD_NOP, in which case this element of iocbs is simply ignored. this "operation" is useful in situations where you have a fixed array of struct iocb elements and only a few of them need to be handled at a time. another situation is where the io_submit(3) call was canceled before all requests were processed and the remaining requests have to be reissued. very main character energy of you to plan ahead like that. 💅

the other members of each element of the array pointed to by iocbs must have values suitable for the operation, as described in the documentation for io_prep_pread(3) and io_prep_pwrite(3) above. 🎀

the function returns immediately after having enqueued all the requests. not me just... dropping them off and leaving 😭

on success, io_submit() returns the number of iocbs submitted successfully. otherwise, -error is returned, where error is one of the Exxx values defined in the Errors section. periodt.

⚠️ if an error is detected, then the behavior is undefined. bestie. i'm serious. 💀

⚠️ simultaneous asynchronous operations using the same iocb produce undefined results. don't do it. i'm begging. 🙈

💜 ERRORS 💜

• EFAULT — iocbs referenced data outside of the program's accessible address space.
• EINVAL — ctx refers to an uninitialized aio context, the iocb pointed to by iocbs contains an improperly initialized iocb,
• EBADF — the iocb contains a file descriptor that does not exist.
• EINVAL — the file specified in the iocb does not support the given io operation.

(yes there are two EINVALs. iconic. she contains multitudes. 👑)

⭐ SEE ALSO ⭐

io(3), io_cancel(3), io_fsync(3), io_getevents(3), io_prep_fsync(3), io_prep_pread(3), io_prep_pwrite(3), io_queue_init(3), io_queue_release(3), io_queue_run(3), io_queue_wait(3), io_set_callback(3), errno(3).

and that's the page, bestie!! 🎀 go forth and submit your iocbs responsibly ✨

this one's from the Linux crew, dated 2019-07-23 — so yeah, she's got a lil vintage moment going on, but she still eats 💅🦋