io_submit

Partial in Antinomie 0.7.0 · Syscall list

Synopsis

long io_submit(aio_context_t ctx_id, long nr, struct iocb **iocbpp);

Number (x86-64)	209
ABI	64
Kernel entry point	sys_io_submit

This is the raw kernel prototype from the pinned Linux 6.12.94 schema, not the libc wrapper.

Description

Submits one or more asynchronous I/O requests, described by iocb structures, to an AIO context.

Arguments

Name	Type	Meaning
ctx_id (arg0)	aio_context_t	AIO context handle.
nr (arg1)	long	Number of items.
iocbpp (arg2)	struct iocb **	Pointer to an array of pointers to iocb structures.

Return value

On success: the number of requests submitted.

In an Antinomie trace the Return column and the ret filter field show the raw kernel return value. On failure that is the negative errno, for example -2 for ENOENT, not the -1 plus errno that the libc wrapper gives. syscall.errno holds the positive errno and syscall.success is false.

Common errors

Raw return	Name	Meaning
-11	EAGAIN	The call would block, or a resource is temporarily unavailable.
-9	EBADF	A file descriptor is not valid for this operation.
-22	EINVAL	An argument is invalid.

Man page

io_submit(2) on man7.org

Captured by Antinomie

Coverage mark: Partial. Request types without a decoder (anything other than read, write, vectored read/write, fsync, fdsync and poll) are recorded with a “no decoder” gap, and the output buffer of a plain PREAD is read later, when the program collects the result.

Every call is recorded as an Entry record (the six argument words and the pointees copied at entry) and an Exit record (the return value and the pointees copied at exit).

Arguments

Argument	When	How	Recorded field key	Condition
ctx_id (arg0)	Entry	raw scalar word	args.0, args.ctx_id
nr (arg1)	Entry	raw scalar word	args.1, args.nr
iocbpp (arg2)	Entry	the pointer itself, as a raw word	args.2, args.raw[2]
↳ pointee	Entry	array of pointers to iocb, count from nr (arg1)	arg2.iocbpp	always
↳ pointee	Entry	each pointer, then the iocb structure it points to	arg2.iocbpp[i], arg2.iocb[i]	always
↳ pointee	Entry	array of iovec (count from aio_nbytes, at most 1,024)	arg2.iocb[i].iov	the request is PREADV or PWRITEV
↳ pointee	Entry	buffer, length aio_nbytes	arg2.iocb[i].input	the request is PWRITE
↳ pointee	Entry	buffer, length aio_nbytes, status “not observed asynchronously”	arg2.iocb[i].output	the request is PREAD
↳ pointee	Entry	address only, status “no decoder”	arg2.iocb[i].variant	the request is none of the above and not fsync, fdsync or poll

Family notes

• Each submitted iocb is copied (arg2.iocb[i]). For vectored requests the iovec array (arg2.iocb[i].iov) is copied; for writes the input buffer (arg2.iocb[i].input) is copied; for a plain read the output buffer is read later, when the program collects the result (stage “Reaped”).

Filter fields

• Result: ret, syscall.errno, syscall.success, syscall.duration_ns.
• Argument words: args.ctx_id (arg0), args.nr (arg1), args.iocbpp (arg2); args.0 to args.5 by position.

See Syscall Trace filter for the full syntax.

Known gaps

• The content of a plain PREAD is read later, when the program collects the result; see Async observations.
• See the coverage mark above for the code paths that record a gap.

For what the capture statuses mean, see Capture statuses. For what is never recorded, see Known gaps.