.\" Copyright 2003, Free Software Foundation, Inc.
.\" Copyright, the authors of the Linux man-pages project
.\"
.\" SPDX-License-Identifier: GPL-1.0-or-later
.\"
.TH io_setup 2 2026-04-11 "Linux man-pages 6.19"
.SH NAME
io_setup \- create an asynchronous I/O context
.SH LIBRARY
Standard C library
.RI ( libc ,\~ \-lc )
.SH SYNOPSIS
.nf
.B #include <linux/aio_abi.h>
.BR "#include <sys/syscall.h>" "    /* Definition of SYS_* constants */"
.B #include <unistd.h>
.P
.BI "long\~syscall(SYS_io_setup, unsigned int " n ", aio_context_t *" ctx_idp );
.fi
.SH DESCRIPTION
.IR Note :
you probably want to use the
.BR io_setup (3)
wrapper function provided by
.IR libaio ;
see VERSIONS.
.P
The
.BR io_setup ()
system call
creates an asynchronous I/O context suitable for concurrently processing
.I n
operations.
The
.I ctx_idp
argument must not point to an AIO context that already exists, and must
be initialized to 0 prior to the call.
On successful creation of the AIO context,
.I *ctx_idp
is filled in
with the resulting handle.
.SH RETURN VALUE
On success,
.BR io_setup ()
returns 0.
On error,
\-1 is returned,
and
.I errno
is set to indicate the error.
.SH ERRORS
.TP
.B EAGAIN
The specified
.I n
exceeds the limit of available events,
as defined in
.I /proc/sys/fs/aio\-max\-nr
(see
.BR proc_sys_fs (5)).
.TP
.B EFAULT
An invalid pointer is passed for
.IR ctx_idp .
.TP
.B EINVAL
.I *ctx_idp
is not initialized to 0.
.TP
.B EINVAL
The specified
.I n
exceeds internal limits.
.I n
should be greater than 0.
.TP
.B ENOMEM
Insufficient kernel resources are available.
.TP
.B ENOSYS
.BR io_setup ()
is not implemented on this architecture.
.SH VERSIONS
.UR https://pagure.io/libaio
.I libaio
.UE
provides a wrapper function with the same name,
but different prototype and return value.
You probably want to use that wrapper.
.SH STANDARDS
Linux.
.SH HISTORY
Linux 2.5.
.SH SEE ALSO
.BR io_cancel (2),
.BR io_destroy (2),
.BR io_getevents (2),
.BR io_submit (2),
.BR io_setup (3),
.BR aio (7)
.\" .SH AUTHOR
.\" Kent Yoder.