|
Packit |
7cfc04 |
.\" Copyright (C) 2003 Davide Libenzi
|
|
Packit |
7cfc04 |
.\" Davide Libenzi <davidel@xmailserver.org>
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" %%%LICENSE_START(GPLv2+_SW_3_PARA)
|
|
Packit |
7cfc04 |
.\" This program is free software; you can redistribute it and/or modify
|
|
Packit |
7cfc04 |
.\" it under the terms of the GNU General Public License as published by
|
|
Packit |
7cfc04 |
.\" the Free Software Foundation; either version 2 of the License, or
|
|
Packit |
7cfc04 |
.\" (at your option) any later version.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" This program is distributed in the hope that it will be useful,
|
|
Packit |
7cfc04 |
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
Packit |
7cfc04 |
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
Packit |
7cfc04 |
.\" GNU General Public License for more details.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" You should have received a copy of the GNU General Public
|
|
Packit |
7cfc04 |
.\" License along with this manual; if not, see
|
|
Packit |
7cfc04 |
.\" <http://www.gnu.org/licenses/>.
|
|
Packit |
7cfc04 |
.\" %%%LICENSE_END
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" Modified 2004-06-17 by Michael Kerrisk <mtk.manpages@gmail.com>
|
|
Packit |
7cfc04 |
.\" Modified 2005-04-04 by Marko Kohtala <marko.kohtala@gmail.com>
|
|
Packit |
7cfc04 |
.\" 2008-10-10, mtk: add description of epoll_create1()
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.TH EPOLL_CREATE 2 2017-09-15 "Linux" "Linux Programmer's Manual"
|
|
Packit |
7cfc04 |
.SH NAME
|
|
Packit |
7cfc04 |
epoll_create, epoll_create1 \- open an epoll file descriptor
|
|
Packit |
7cfc04 |
.SH SYNOPSIS
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
.B #include <sys/epoll.h>
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.BI "int epoll_create(int " size );
|
|
Packit |
7cfc04 |
.BI "int epoll_create1(int " flags );
|
|
Packit |
7cfc04 |
.fi
|
|
Packit |
7cfc04 |
.SH DESCRIPTION
|
|
Packit |
7cfc04 |
.BR epoll_create ()
|
|
Packit |
7cfc04 |
creates a new
|
|
Packit |
7cfc04 |
.BR epoll (7)
|
|
Packit |
7cfc04 |
instance.
|
|
Packit |
7cfc04 |
Since Linux 2.6.8, the
|
|
Packit |
7cfc04 |
.I size
|
|
Packit |
7cfc04 |
argument is ignored, but must be greater than zero; see NOTES below.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.BR epoll_create ()
|
|
Packit |
7cfc04 |
returns a file descriptor referring to the new epoll instance.
|
|
Packit |
7cfc04 |
This file descriptor is used for all the subsequent calls to the
|
|
Packit |
7cfc04 |
.B epoll
|
|
Packit |
7cfc04 |
interface.
|
|
Packit |
7cfc04 |
When no longer required, the file descriptor returned by
|
|
Packit |
7cfc04 |
.BR epoll_create ()
|
|
Packit |
7cfc04 |
should be closed by using
|
|
Packit |
7cfc04 |
.BR close (2).
|
|
Packit |
7cfc04 |
When all file descriptors referring to an epoll instance have been closed,
|
|
Packit |
7cfc04 |
the kernel destroys the instance
|
|
Packit |
7cfc04 |
and releases the associated resources for reuse.
|
|
Packit |
7cfc04 |
.SS epoll_create1()
|
|
Packit |
7cfc04 |
If
|
|
Packit |
7cfc04 |
.I flags
|
|
Packit |
7cfc04 |
is 0, then, other than the fact that the obsolete
|
|
Packit |
7cfc04 |
.I size
|
|
Packit |
7cfc04 |
argument is dropped,
|
|
Packit |
7cfc04 |
.BR epoll_create1 ()
|
|
Packit |
7cfc04 |
is the same as
|
|
Packit |
7cfc04 |
.BR epoll_create ().
|
|
Packit |
7cfc04 |
The following value can be included in
|
|
Packit |
7cfc04 |
.IR flags
|
|
Packit |
7cfc04 |
to obtain different behavior:
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EPOLL_CLOEXEC
|
|
Packit |
7cfc04 |
Set the close-on-exec
|
|
Packit |
7cfc04 |
.RB ( FD_CLOEXEC )
|
|
Packit |
7cfc04 |
flag on the new file descriptor.
|
|
Packit |
7cfc04 |
See the description of the
|
|
Packit |
7cfc04 |
.B O_CLOEXEC
|
|
Packit |
7cfc04 |
flag in
|
|
Packit |
7cfc04 |
.BR open (2)
|
|
Packit |
7cfc04 |
for reasons why this may be useful.
|
|
Packit |
7cfc04 |
.SH RETURN VALUE
|
|
Packit |
7cfc04 |
On success,
|
|
Packit |
7cfc04 |
these system calls
|
|
Packit |
7cfc04 |
return a nonnegative file descriptor.
|
|
Packit |
7cfc04 |
On error, \-1 is returned, and
|
|
Packit |
7cfc04 |
.I errno
|
|
Packit |
7cfc04 |
is set to indicate the error.
|
|
Packit |
7cfc04 |
.SH ERRORS
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EINVAL
|
|
Packit |
7cfc04 |
.I size
|
|
Packit |
7cfc04 |
is not positive.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EINVAL
|
|
Packit |
7cfc04 |
.RB ( epoll_create1 ())
|
|
Packit |
7cfc04 |
Invalid value specified in
|
|
Packit |
7cfc04 |
.IR flags .
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EMFILE
|
|
Packit |
7cfc04 |
The per-user limit on the number of epoll instances imposed by
|
|
Packit |
7cfc04 |
.I /proc/sys/fs/epoll/max_user_instances
|
|
Packit |
7cfc04 |
was encountered.
|
|
Packit |
7cfc04 |
See
|
|
Packit |
7cfc04 |
.BR epoll (7)
|
|
Packit |
7cfc04 |
for further details.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EMFILE
|
|
Packit |
7cfc04 |
The per-process limit on the number of open file descriptors has been reached.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B ENFILE
|
|
Packit |
7cfc04 |
The system-wide limit on the total number of open files has been reached.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B ENOMEM
|
|
Packit |
7cfc04 |
There was insufficient memory to create the kernel object.
|
|
Packit |
7cfc04 |
.SH VERSIONS
|
|
Packit |
7cfc04 |
.BR epoll_create ()
|
|
Packit |
7cfc04 |
was added to the kernel in version 2.6.
|
|
Packit |
7cfc04 |
Library support is provided in glibc starting with version 2.3.2.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.\" To be precise: kernel 2.5.44.
|
|
Packit |
7cfc04 |
.\" The interface should be finalized by Linux kernel 2.5.66.
|
|
Packit |
7cfc04 |
.BR epoll_create1 ()
|
|
Packit |
7cfc04 |
was added to the kernel in version 2.6.27.
|
|
Packit |
7cfc04 |
Library support is provided in glibc starting with version 2.9.
|
|
Packit |
7cfc04 |
.SH CONFORMING TO
|
|
Packit |
7cfc04 |
.BR epoll_create ()
|
|
Packit |
7cfc04 |
is Linux-specific.
|
|
Packit |
7cfc04 |
.SH NOTES
|
|
Packit |
7cfc04 |
In the initial
|
|
Packit |
7cfc04 |
.BR epoll_create ()
|
|
Packit |
7cfc04 |
implementation, the
|
|
Packit |
7cfc04 |
.I size
|
|
Packit |
7cfc04 |
argument informed the kernel of the number of file descriptors
|
|
Packit |
7cfc04 |
that the caller expected to add to the
|
|
Packit |
7cfc04 |
.B epoll
|
|
Packit |
7cfc04 |
instance.
|
|
Packit |
7cfc04 |
The kernel used this information as a hint for the amount of
|
|
Packit |
7cfc04 |
space to initially allocate in internal data structures describing events.
|
|
Packit |
7cfc04 |
(If necessary, the kernel would allocate more space
|
|
Packit |
7cfc04 |
if the caller's usage exceeded the hint given in
|
|
Packit |
7cfc04 |
.IR size .)
|
|
Packit |
7cfc04 |
Nowadays,
|
|
Packit |
7cfc04 |
this hint is no longer required
|
|
Packit |
7cfc04 |
(the kernel dynamically sizes the required data structures
|
|
Packit |
7cfc04 |
without needing the hint), but
|
|
Packit |
7cfc04 |
.I size
|
|
Packit |
7cfc04 |
must still be greater than zero,
|
|
Packit |
7cfc04 |
in order to ensure backward compatibility when new
|
|
Packit |
7cfc04 |
.B epoll
|
|
Packit |
7cfc04 |
applications are run on older kernels.
|
|
Packit |
7cfc04 |
.SH SEE ALSO
|
|
Packit |
7cfc04 |
.BR close (2),
|
|
Packit |
7cfc04 |
.BR epoll_ctl (2),
|
|
Packit |
7cfc04 |
.BR epoll_wait (2),
|
|
Packit |
7cfc04 |
.BR epoll (7)
|
|
Packit |
7cfc04 |
.SH COLOPHON
|
|
Packit |
7cfc04 |
This page is part of release 4.15 of the Linux
|
|
Packit |
7cfc04 |
.I man-pages
|
|
Packit |
7cfc04 |
project.
|
|
Packit |
7cfc04 |
A description of the project,
|
|
Packit |
7cfc04 |
information about reporting bugs,
|
|
Packit |
7cfc04 |
and the latest version of this page,
|
|
Packit |
7cfc04 |
can be found at
|
|
Packit |
7cfc04 |
\%https://www.kernel.org/doc/man\-pages/.
|