---
name: "io_submit"
section: "3"
platform: "linux"
package: "libaio"
version: "0.3.113-5"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/io_submit/3"
---

# io\_submit(3)

Submit io requests

## NAME

io\_submit - Submit io requests

## 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

**io\_submit**() submits *nr* iocbs for processing for a given io context ctx.

The  **io\_submit**() function can be used to enqueue an arbitrary number of read and write requests at one time.  The requests can all be meant for the same file, all for different files or every solution in between.

**io\_submit**() gets the  *nr* requests from the array pointed to by *iocbs*. The operation to be performed is determined by the *aio\_lio\_opcode* member in each element of  *iocbs*. If this field is **IO\_CMD\_PREAD** a read operation is 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 is 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 one has a fixed array of **struct iocb** elements from which only a few need to be handled at a time.  Another situation is where the  [**io\_submit**(3)](/io_submit/3.md) call was canceled before all requests are processed  and the remaining requests have to be reissued.

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)](/io_prep_pread/3.md) and  [**io\_prep\_pwrite**(3)](/io_prep_pwrite/3.md) above.

The function returns immediately after having enqueued all the requests.   On success, **io\_submit**() returns the number of iocbs submitted successfully.  Otherwise, -error is return, where  error is one of the Exxx values defined in the Errors section.

If an error is detected, then the behavior is undefined.

Simultaneous asynchronous operations using the same iocb produce undefined results.

## 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.

## SEE ALSO

[**io**(3)](/io/3.md), [**io\_cancel**(3)](/io_cancel/3.md), [**io\_fsync**(3)](/io_fsync/3.md), [**io\_getevents**(3)](/io_getevents/3.md), [**io\_prep\_fsync**(3)](/io_prep_fsync/3.md), [**io\_prep\_pread**(3)](/io_prep_pread/3.md), [**io\_prep\_pwrite**(3)](/io_prep_pwrite/3.md), [**io\_queue\_init**(3)](/io_queue_init/3.md), [**io\_queue\_release**(3)](/io_queue_release/3.md), [**io\_queue\_run**(3)](/io_queue_run/3.md), [**io\_queue\_wait**(3)](/io_queue_wait/3.md), [**io\_set\_callback**(3)](/io_set_callback/3.md), [**errno**(3)](/errno/3.md).