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