epoll_create(2)

1epoll_create(2)               System Calls Manual              epoll_create(2)
2
3
4

NAME

6       epoll_create, epoll_create1 - open an epoll file descriptor
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <sys/epoll.h>
13
14       int epoll_create(int size);
15       int epoll_create1(int flags);
16

DESCRIPTION

18       epoll_create() creates a new epoll(7) instance.  Since Linux 2.6.8, the
19       size argument is ignored, but must be greater than zero; see HISTORY.
20
21       epoll_create() returns a file descriptor referring to the new epoll in‐
22       stance.   This  file descriptor is used for all the subsequent calls to
23       the epoll interface.  When no longer required, the file descriptor  re‐
24       turned  by epoll_create() should be closed by using close(2).  When all
25       file descriptors referring to an epoll instance have been  closed,  the
26       kernel  destroys the instance and releases the associated resources for
27       reuse.
28
29   epoll_create1()
30       If flags is 0, then, other than the fact that the obsolete  size  argu‐
31       ment  is  dropped,  epoll_create1() is the same as epoll_create().  The
32       following value can be included in flags to obtain different behavior:
33
34       EPOLL_CLOEXEC
35              Set the close-on-exec (FD_CLOEXEC) flag on the new file descrip‐
36              tor.   See  the description of the O_CLOEXEC flag in open(2) for
37              reasons why this may be useful.
38

RETURN VALUE

40       On success, these system calls return a file descriptor (a  nonnegative
41       integer).   On  error, -1 is returned, and errno is set to indicate the
42       error.
43

ERRORS

45       EINVAL size is not positive.
46
47       EINVAL (epoll_create1()) Invalid value specified in flags.
48
49       EMFILE The per-process limit on the number of open file descriptors has
50              been reached.
51
52       ENFILE The system-wide limit on the total number of open files has been
53              reached.
54
55       ENOMEM There was insufficient memory to create the kernel object.
56

STANDARDS

58       Linux.
59

HISTORY

61       epoll_create()
62              Linux 2.6, glibc 2.3.2.
63
64       epoll_create1()
65              Linux 2.6.27, glibc 2.9.
66
67       In the initial epoll_create() implementation,  the  size  argument  in‐
68       formed the kernel of the number of file descriptors that the caller ex‐
69       pected to add to the epoll instance.  The kernel used this  information
70       as  a  hint  for  the amount of space to initially allocate in internal
71       data structures describing events.  (If necessary, the kernel would al‐
72       locate  more  space  if  the  caller's usage exceeded the hint given in
73       size.)  Nowadays, this hint is no longer required (the  kernel  dynami‐
74       cally sizes the required data structures without needing the hint), but
75       size must still be greater than zero, in order to ensure backward  com‐
76       patibility when new epoll applications are run on older kernels.
77
78       Prior  to  Linux 2.6.29, a /proc/sys/fs/epoll/max_user_instances kernel
79       parameter limited live  epolls  for  each  real  user  ID,  and  caused
80       epoll_create() to fail with EMFILE on overrun.
81