Debian Codegraph @

upstream/debian-trixie/man2/io_setup.2

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