Debian Codegraph @

upstream/mageia-cauldron/man2/io_setup.2

raw
1 .\" Copyright 2003, Free Software Foundation, Inc.
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: GPL-1.0-or-later
5 .\"
6 .TH io_setup 2 2025-09-21 "Linux man-pages 6.17"
7 .SH NAME
8 io_setup \- create an asynchronous I/O context
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .P
13 Alternatively, Asynchronous I/O library
14 .RI ( libaio ,\~ \-laio );
15 see VERSIONS.
16 .SH SYNOPSIS
17 .nf
18 .BR "#include <linux/aio_abi.h>" " /* Defines needed types */"
19 .P
20 .BI "long io_setup(unsigned int " nr_events ", aio_context_t *" ctx_idp );
21 .fi
22 .P
23 .IR Note :
24 There is no glibc wrapper for this system call;
25 see VERSIONS.
26 .SH DESCRIPTION
27 .IR Note :
28 this page describes the raw Linux system call interface.
29 The wrapper function provided by
30 .I libaio
31 uses a different type for the
32 .I ctx_idp
33 argument.
34 See VERSIONS.
35 .P
36 The
37 .BR io_setup ()
38 system call
39 creates an asynchronous I/O context suitable for concurrently processing
40 .I nr_events
41 operations.
42 The
43 .I ctx_idp
44 argument must not point to an AIO context that already exists, and must
45 be initialized to 0 prior to the call.
46 On successful creation of the AIO context,
47 .I *ctx_idp
48 is filled in
49 with the resulting handle.
50 .SH RETURN VALUE
51 On success,
52 .BR io_setup ()
53 returns 0.
54 For the failure return, see VERSIONS.
55 .SH ERRORS
56 .TP
57 .B EAGAIN
58 The specified
59 .I nr_events
60 exceeds the limit of available events,
61 as defined in
62 .I /proc/sys/fs/aio\-max\-nr
63 (see
64 .BR proc (5)).
65 .TP
66 .B EFAULT
67 An invalid pointer is passed for
68 .IR ctx_idp .
69 .TP
70 .B EINVAL
71 .I ctx_idp
72 is not initialized,
73 or the specified
74 .I nr_events
75 exceeds internal limits.
76 .I nr_events
77 should be greater than 0.
78 .TP
79 .B ENOMEM
80 Insufficient kernel resources are available.
81 .TP
82 .B ENOSYS
83 .BR io_setup ()
84 is not implemented on this architecture.
85 .SH VERSIONS
86 glibc does not provide a wrapper for this system call.
87 You could invoke it using
88 .BR syscall (2).
89 But instead, you probably want to use the
90 .BR io_setup ()
91 wrapper function provided by
92 .\" http://git.fedorahosted.org/git/?p=libaio.git
93 .IR libaio .
94 .P
95 Note that the
96 .I libaio
97 wrapper function uses a different type
98 .RI ( "io_context_t\ *" )
99 .\" But glibc is confused, since <libaio.h> uses 'io_context_t' to declare
100 .\" the system call.
101 for the
102 .I ctx_idp
103 argument.
104 Note also that the
105 .I libaio
106 wrapper does not follow the usual C library conventions for indicating errors:
107 on error it returns a negated error number
108 (the negative of one of the values listed in ERRORS).
109 If the system call is invoked via
110 .BR syscall (2),
111 then the return value follows the usual conventions for
112 indicating an error: \-1, with
113 .I errno
114 set to a (positive) value that indicates the error.
115 .SH STANDARDS
116 Linux.
117 .SH HISTORY
118 Linux 2.5.
119 .SH SEE ALSO
120 .BR io_cancel (2),
121 .BR io_destroy (2),
122 .BR io_getevents (2),
123 .BR io_submit (2),
124 .BR aio (7)
125 .\" .SH AUTHOR
126 .\" Kent Yoder.