]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Copyright (C) 2003 Davide Libenzi |
962a269d | 2 | .\" and Copyright 2008, 2009, 2012 Michael Kerrisk <tk.manpages@gmail.com> |
4366109b | 3 | .\" Davide Libenzi <davidel@xmailserver.org> |
fea681da | 4 | .\" |
e4a74ca8 | 5 | .\" SPDX-License-Identifier: GPL-2.0-or-later |
fea681da | 6 | .\" |
c11b1abf | 7 | .\" Modified 2004-06-17 by Michael Kerrisk <mtk.manpages@gmail.com> |
3d9a2200 | 8 | .\" Modified 2005-04-04 by Marko Kohtala <marko.kohtala@gmail.com> |
272fa3cb | 9 | .\" 2008-10-10, mtk: add description of epoll_create1() |
fea681da | 10 | .\" |
1d767b55 | 11 | .TH EPOLL_CREATE 2 2021-03-22 "Linux" "Linux Programmer's Manual" |
fea681da | 12 | .SH NAME |
272fa3cb | 13 | epoll_create, epoll_create1 \- open an epoll file descriptor |
ee5c804b AC |
14 | .SH LIBRARY |
15 | Standard C library | |
8fc3b2cf | 16 | .RI ( libc ", " \-lc ) |
fea681da | 17 | .SH SYNOPSIS |
272fa3cb | 18 | .nf |
fea681da | 19 | .B #include <sys/epoll.h> |
68e4db0a | 20 | .PP |
52e87bbe | 21 | .BI "int epoll_create(int " size ); |
272fa3cb MK |
22 | .BI "int epoll_create1(int " flags ); |
23 | .fi | |
fea681da | 24 | .SH DESCRIPTION |
272fa3cb | 25 | .BR epoll_create () |
65c031fb | 26 | creates a new |
5f4e9d5a | 27 | .BR epoll (7) |
fde633de MK |
28 | instance. |
29 | Since Linux 2.6.8, the | |
272fa3cb | 30 | .I size |
cce4f974 | 31 | argument is ignored, but must be greater than zero; see NOTES. |
efeece04 | 32 | .PP |
700e0efd MK |
33 | .BR epoll_create () |
34 | returns a file descriptor referring to the new epoll instance. | |
35 | This file descriptor is used for all the subsequent calls to the | |
fea681da | 36 | .B epoll |
c13182ef | 37 | interface. |
700e0efd | 38 | When no longer required, the file descriptor returned by |
2777b1ca | 39 | .BR epoll_create () |
700e0efd | 40 | should be closed by using |
fea681da | 41 | .BR close (2). |
700e0efd MK |
42 | When all file descriptors referring to an epoll instance have been closed, |
43 | the kernel destroys the instance | |
3b777aff | 44 | and releases the associated resources for reuse. |
6b6f5404 | 45 | .SS epoll_create1() |
272fa3cb MK |
46 | If |
47 | .I flags | |
48 | is 0, then, other than the fact that the obsolete | |
e1fbfba5 | 49 | .I size |
272fa3cb MK |
50 | argument is dropped, |
51 | .BR epoll_create1 () | |
52 | is the same as | |
53 | .BR epoll_create (). | |
54 | The following value can be included in | |
1ae6b2c7 | 55 | .I flags |
272fa3cb MK |
56 | to obtain different behavior: |
57 | .TP | |
58 | .B EPOLL_CLOEXEC | |
59 | Set the close-on-exec | |
9c9cccf7 | 60 | .RB ( FD_CLOEXEC ) |
272fa3cb | 61 | flag on the new file descriptor. |
c5571b61 | 62 | See the description of the |
272fa3cb MK |
63 | .B O_CLOEXEC |
64 | flag in | |
65 | .BR open (2) | |
66 | for reasons why this may be useful. | |
47297adb | 67 | .SH RETURN VALUE |
c5571b61 | 68 | On success, |
272fa3cb | 69 | these system calls |
ed09120a | 70 | return a file descriptor (a nonnegative integer). |
272fa3cb | 71 | On error, \-1 is returned, and |
fea681da | 72 | .I errno |
272fa3cb | 73 | is set to indicate the error. |
fea681da MK |
74 | .SH ERRORS |
75 | .TP | |
3d9a2200 MK |
76 | .B EINVAL |
77 | .I size | |
78 | is not positive. | |
79 | .TP | |
272fa3cb MK |
80 | .B EINVAL |
81 | .RB ( epoll_create1 ()) | |
82 | Invalid value specified in | |
83 | .IR flags . | |
84 | .TP | |
1c7a3214 MK |
85 | .B EMFILE |
86 | The per-user limit on the number of epoll instances imposed by | |
87 | .I /proc/sys/fs/epoll/max_user_instances | |
88 | was encountered. | |
89 | See | |
90 | .BR epoll (7) | |
91 | for further details. | |
92 | .TP | |
6bde54af MK |
93 | .B EMFILE |
94 | The per-process limit on the number of open file descriptors has been reached. | |
95 | .TP | |
fea681da | 96 | .B ENFILE |
e258766b | 97 | The system-wide limit on the total number of open files has been reached. |
fea681da MK |
98 | .TP |
99 | .B ENOMEM | |
100 | There was insufficient memory to create the kernel object. | |
6c3529d8 | 101 | .SH VERSIONS |
2777b1ca | 102 | .BR epoll_create () |
6c3529d8 MK |
103 | was added to the kernel in version 2.6. |
104 | Library support is provided in glibc starting with version 2.3.2. | |
efeece04 | 105 | .PP |
6c3529d8 | 106 | .\" To be precise: kernel 2.5.44. |
75b48e9d | 107 | .\" The interface should be finalized by Linux kernel 2.5.66. |
6c3529d8 MK |
108 | .BR epoll_create1 () |
109 | was added to the kernel in version 2.6.27. | |
110 | Library support is provided in glibc starting with version 2.9. | |
111 | .SH CONFORMING TO | |
112 | .BR epoll_create () | |
e4c07f64 MK |
113 | and |
114 | .BR epoll_create1 () | |
115 | are Linux-specific. | |
9967820f | 116 | .SH NOTES |
fde633de MK |
117 | In the initial |
118 | .BR epoll_create () | |
119 | implementation, the | |
120 | .I size | |
121 | argument informed the kernel of the number of file descriptors | |
122 | that the caller expected to add to the | |
123 | .B epoll | |
124 | instance. | |
125 | The kernel used this information as a hint for the amount of | |
126 | space to initially allocate in internal data structures describing events. | |
127 | (If necessary, the kernel would allocate more space | |
128 | if the caller's usage exceeded the hint given in | |
129 | .IR size .) | |
130 | Nowadays, | |
131 | this hint is no longer required | |
132 | (the kernel dynamically sizes the required data structures | |
133 | without needing the hint), but | |
9967820f | 134 | .I size |
fde633de MK |
135 | must still be greater than zero, |
136 | in order to ensure backward compatibility when new | |
137 | .B epoll | |
138 | applications are run on older kernels. | |
47297adb | 139 | .SH SEE ALSO |
fea681da MK |
140 | .BR close (2), |
141 | .BR epoll_ctl (2), | |
142 | .BR epoll_wait (2), | |
2315114c | 143 | .BR epoll (7) |