]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (C) 2003 Free Software Foundation, Inc. |
2 | .\" This file is distributed according to the GNU General Public License. | |
3 | .\" See the file COPYING in the top level source directory for details. | |
4 | .\" | |
45c99e3e | 5 | .TH IO_SETUP 2 2012-07-13 "Linux" "Linux Programmer's Manual" |
fea681da | 6 | .SH NAME |
d12c1424 | 7 | io_setup \- create an asynchronous I/O context |
47297adb | 8 | .SH SYNOPSIS |
d12c1424 | 9 | .nf |
e1c5ebfa MK |
10 | .BR "#include <linux/aio_abi.h>" " /* Defines needed types */" |
11 | ||
12 | .BI "int io_setup(unsigned " nr_events ", aio_context_t *" ctx_idp ); | |
d12c1424 | 13 | .fi |
45c99e3e MK |
14 | |
15 | .IR Note : | |
16 | There is no glibc wrapper for this system call; see NOTES. | |
47297adb | 17 | .SH DESCRIPTION |
fea681da | 18 | .PP |
e1c5ebfa | 19 | The |
60a90ecd | 20 | .BR io_setup () |
e1c5ebfa | 21 | system call |
60a90ecd | 22 | creates an asynchronous I/O context capable of receiving |
a8d55537 | 23 | at least \fInr_events\fP. |
e1c5ebfa MK |
24 | The |
25 | .I ctx_idp | |
26 | argument must not point to an AIO context that already exists, and must | |
c13182ef | 27 | be initialized to 0 prior to the call. |
e1c5ebfa | 28 | On successful creation of the AIO context, \fI*ctx_idp\fP is filled in |
fea681da | 29 | with the resulting handle. |
47297adb | 30 | .SH RETURN VALUE |
24d2f49a MK |
31 | On success, |
32 | .BR io_setup () | |
33 | returns 0. | |
34 | For the failure return, see NOTES. | |
47297adb | 35 | .SH ERRORS |
fea681da | 36 | .TP |
c4e45390 MK |
37 | .B EAGAIN |
38 | The specified \fInr_events\fP exceeds the user's limit of available events. | |
fea681da | 39 | .TP |
d12c1424 | 40 | .B EFAULT |
e1c5ebfa | 41 | An invalid pointer is passed for \fIctx_idp\fP. |
fea681da | 42 | .TP |
c4e45390 | 43 | .B EINVAL |
e1c5ebfa | 44 | \fIctx_idp\fP is not initialized, or the specified \fInr_events\fP |
67da5267 MK |
45 | exceeds internal limits. |
46 | \fInr_events\fP should be greater than 0. | |
c4e45390 | 47 | .TP |
d12c1424 | 48 | .B ENOMEM |
fea681da | 49 | Insufficient kernel resources are available. |
fea681da | 50 | .TP |
d12c1424 | 51 | .B ENOSYS |
60a90ecd MK |
52 | .BR io_setup () |
53 | is not implemented on this architecture. | |
47297adb | 54 | .SH VERSIONS |
a1d5f77c | 55 | .PP |
e1c5ebfa | 56 | The asynchronous I/O system calls first appeared in Linux 2.5. |
47297adb | 57 | .SH CONFORMING TO |
fea681da | 58 | .PP |
60a90ecd | 59 | .BR io_setup () |
8382f16d | 60 | is Linux-specific and should not be used in programs |
fea681da | 61 | that are intended to be portable. |
24d2f49a MK |
62 | .SH NOTES |
63 | Glibc does not provide a wrapper function for this system call. | |
e1c5ebfa MK |
64 | You could invoke it using |
65 | .BR syscall (2). | |
66 | But instead, you probably want to use the | |
67 | .BR io_setup () | |
68 | wrapper function provided by | |
69 | .\" http://git.fedorahosted.org/git/?p=libaio.git | |
70 | .IR libaio . | |
24d2f49a | 71 | |
e1c5ebfa | 72 | Note that the |
24d2f49a | 73 | .I libaio |
e1c5ebfa MK |
74 | wrapper function uses a different type |
75 | .RI ( "io_context_t\ *" ) | |
76 | .\" But glibc is confused, since <libaio.h> uses 'io_context_t' to declare | |
77 | .\" the system call. | |
78 | for the | |
79 | .I ctx_idp | |
80 | argument. | |
81 | Note also that the | |
82 | .I libaio | |
83 | wrapper does not follow the usual C library conventions for indicating errors: | |
24d2f49a MK |
84 | on error it returns a negated error number |
85 | (the negative of one of the values listed in ERRORS). | |
86 | If the system call is invoked via | |
87 | .BR syscall (2), | |
88 | then the return value follows the usual conventions for | |
89 | indicating an error: \-1, with | |
90 | .I errno | |
91 | set to a (positive) value that indicates the error. | |
47297adb | 92 | .SH SEE ALSO |
c4e45390 | 93 | .BR io_cancel (2), |
60a90ecd MK |
94 | .BR io_destroy (2), |
95 | .BR io_getevents (2), | |
ff0c3278 MK |
96 | .BR io_submit (2), |
97 | .BR aio (7) | |
d12c1424 MK |
98 | .\" .SH AUTHOR |
99 | .\" Kent Yoder. |