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