Debian Codegraph @

upstream/debian-trixie/man2/epoll_create.2

raw
1 .\" Copyright (C) 2003 Davide Libenzi
2 .\" and Copyright 2008, 2009, 2012 Michael Kerrisk <[email protected]>
3 .\" Davide Libenzi <[email protected]>
4 .\"
5 .\" SPDX-License-Identifier: GPL-2.0-or-later
6 .\"
7 .\" Modified 2004-06-17 by Michael Kerrisk <[email protected]>
8 .\" Modified 2005-04-04 by Marko Kohtala <[email protected]>
9 .\" 2008-10-10, mtk: add description of epoll_create1()
10 .\"
11 .TH epoll_create 2 2024-06-12 "Linux man-pages 6.9.1"
12 .SH NAME
13 epoll_create, epoll_create1 \- open an epoll file descriptor
14 .SH LIBRARY
15 Standard C library
16 .RI ( libc ", " \-lc )
17 .SH SYNOPSIS
18 .nf
19 .B #include <sys/epoll.h>
20 .P
21 .BI "int epoll_create(int " size );
22 .BI "int epoll_create1(int " flags );
23 .fi
24 .SH DESCRIPTION
25 .BR epoll_create ()
26 creates a new
27 .BR epoll (7)
28 instance.
29 Since Linux 2.6.8, the
30 .I size
31 argument is ignored, but must be greater than zero; see HISTORY.
32 .P
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
36 .B epoll
37 interface.
38 When no longer required, the file descriptor returned by
39 .BR epoll_create ()
40 should be closed by using
41 .BR close (2).
42 When all file descriptors referring to an epoll instance have been closed,
43 the kernel destroys the instance
44 and releases the associated resources for reuse.
45 .SS epoll_create1()
46 If
47 .I flags
48 is 0, then, other than the fact that the obsolete
49 .I size
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
55 .I flags
56 to obtain different behavior:
57 .TP
58 .B EPOLL_CLOEXEC
59 Set the close-on-exec
60 .RB ( FD_CLOEXEC )
61 flag on the new file descriptor.
62 See the description of the
63 .B O_CLOEXEC
64 flag in
65 .BR open (2)
66 for reasons why this may be useful.
67 .SH RETURN VALUE
68 On success,
69 these system calls
70 return a file descriptor (a nonnegative integer).
71 On error, \-1 is returned, and
72 .I errno
73 is set to indicate the error.
74 .SH ERRORS
75 .TP
76 .B EINVAL
77 .I size
78 is not positive.
79 .TP
80 .B EINVAL
81 .RB ( epoll_create1 ())
82 Invalid value specified in
83 .IR flags .
84 .TP
85 .B EMFILE
86 The per-process limit on the number of open file descriptors has been reached.
87 .TP
88 .B ENFILE
89 The system-wide limit on the total number of open files has been reached.
90 .TP
91 .B ENOMEM
92 There was insufficient memory to create the kernel object.
93 .SH STANDARDS
94 Linux.
95 .SH HISTORY
96 .TP
97 .BR epoll_create ()
98 Linux 2.6,
99 glibc 2.3.2.
100 .\" To be precise: kernel 2.5.44.
101 .\" The interface should be finalized by Linux kernel 2.5.66.
102 .TP
103 .BR epoll_create1 ()
104 Linux 2.6.27,
105 glibc 2.9.
106 .P
107 In the initial
108 .BR epoll_create ()
109 implementation, the
110 .I size
111 argument informed the kernel of the number of file descriptors
112 that the caller expected to add to the
113 .B epoll
114 instance.
115 The kernel used this information as a hint for the amount of
116 space to initially allocate in internal data structures describing events.
117 (If necessary, the kernel would allocate more space
118 if the caller's usage exceeded the hint given in
119 .IR size .)
120 Nowadays,
121 this hint is no longer required
122 (the kernel dynamically sizes the required data structures
123 without needing the hint), but
124 .I size
125 must still be greater than zero,
126 in order to ensure backward compatibility when new
127 .B epoll
128 applications are run on older kernels.
129 .P
130 Prior to Linux 2.6.29,
131 .\" commit 9df04e1f25effde823a600e755b51475d438f56b
132 a
133 .I /proc/sys/fs/epoll/max_user_instances
134 kernel parameter limited live epolls for each real user ID,
135 and caused
136 .BR epoll_create ()
137 to fail with
138 .B EMFILE
139 on overrun.
140 .SH SEE ALSO
141 .BR close (2),
142 .BR epoll_ctl (2),
143 .BR epoll_wait (2),
144 .BR ioctl_eventpoll (2),
145 .BR epoll (7)