2004-11-03 13:51:07 +00:00
|
|
|
.\"
|
|
|
|
|
.\" epoll by Davide Libenzi ( efficient event notification retrieval )
|
|
|
|
|
.\" Copyright (C) 2003 Davide Libenzi
|
|
|
|
|
.\"
|
|
|
|
|
.\" This program is free software; you can redistribute it and/or modify
|
|
|
|
|
.\" it under the terms of the GNU General Public License as published by
|
|
|
|
|
.\" the Free Software Foundation; either version 2 of the License, or
|
|
|
|
|
.\" (at your option) any later version.
|
|
|
|
|
.\"
|
|
|
|
|
.\" This program is distributed in the hope that it will be useful,
|
|
|
|
|
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
|
|
|
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
|
|
|
.\" GNU General Public License for more details.
|
|
|
|
|
.\"
|
|
|
|
|
.\" You should have received a copy of the GNU General Public License
|
|
|
|
|
.\" along with this program; if not, write to the Free Software
|
|
|
|
|
.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
|
|
|
|
|
.\"
|
|
|
|
|
.\" Davide Libenzi <davidel@xmailserver.org>
|
|
|
|
|
.\"
|
2007-09-20 06:52:22 +00:00
|
|
|
.\" Modified 2004-06-17 by Michael Kerrisk <mtk.manpages@gmail.com>
|
2005-04-04 16:33:48 +00:00
|
|
|
.\" Modified 2005-04-04 by Marko Kohtala <marko.kohtala@gmail.com>
|
2008-10-10 11:38:11 +00:00
|
|
|
.\" 2008-10-10, mtk: add description of epoll_create1()
|
2004-11-03 13:51:07 +00:00
|
|
|
.\"
|
2012-04-14 19:03:35 +00:00
|
|
|
.TH EPOLL_CREATE 2 2012-04-15 "Linux" "Linux Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
2008-10-10 11:38:11 +00:00
|
|
|
epoll_create, epoll_create1 \- open an epoll file descriptor
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH SYNOPSIS
|
2008-10-10 11:38:11 +00:00
|
|
|
.nf
|
2004-11-03 13:51:07 +00:00
|
|
|
.B #include <sys/epoll.h>
|
|
|
|
|
.sp
|
2007-07-10 04:51:30 +00:00
|
|
|
.BI "int epoll_create(int " size );
|
2008-10-10 11:38:11 +00:00
|
|
|
.BI "int epoll_create1(int " flags );
|
|
|
|
|
.fi
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH DESCRIPTION
|
2008-10-10 11:38:11 +00:00
|
|
|
.BR epoll_create ()
|
2012-04-14 19:03:35 +00:00
|
|
|
creates an
|
|
|
|
|
.BR epoll (7)
|
|
|
|
|
"instance",
|
2009-01-15 18:31:16 +00:00
|
|
|
requesting the kernel to allocate an event backing store dimensioned for
|
2004-11-03 13:51:07 +00:00
|
|
|
.I size
|
2007-04-12 22:42:49 +00:00
|
|
|
descriptors.
|
|
|
|
|
The
|
2004-11-03 13:51:07 +00:00
|
|
|
.I size
|
|
|
|
|
is not the maximum size of the backing store but
|
|
|
|
|
just a hint to the kernel about how to dimension internal structures.
|
2008-10-10 11:38:11 +00:00
|
|
|
(Nowadays,
|
|
|
|
|
.I size
|
2010-12-03 06:20:28 +00:00
|
|
|
is unused; see NOTES below.)
|
2008-10-10 11:38:11 +00:00
|
|
|
|
2009-01-15 18:31:16 +00:00
|
|
|
.BR epoll_create ()
|
|
|
|
|
returns a file descriptor referring to the new epoll instance.
|
|
|
|
|
This file descriptor is used for all the subsequent calls to the
|
2004-11-03 13:51:07 +00:00
|
|
|
.B epoll
|
2007-04-12 22:42:49 +00:00
|
|
|
interface.
|
2009-01-15 18:31:16 +00:00
|
|
|
When no longer required, the file descriptor returned by
|
2007-11-24 10:10:39 +00:00
|
|
|
.BR epoll_create ()
|
2009-01-15 18:31:16 +00:00
|
|
|
should be closed by using
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR close (2).
|
2009-01-15 18:31:16 +00:00
|
|
|
When all file descriptors referring to an epoll instance have been closed,
|
|
|
|
|
the kernel destroys the instance
|
close.2, epoll_create.2, epoll_ctl.2, fcntl.2, madvise.2, mmap.2, mremap.2, select_tut.2, setgid.2, setuid.2, syscalls.2, vmsplice.2, dlopen.3, fts.3, getpw.3, stdio.3, fd.4, initrd.4, random.4, sd.4, bootparam.7, capabilities.7, cpuset.7, epoll.7, inotify.7, man.7, socket.7, x25.7: Global fix: s/re-/re/
The tendency in English, as prescribed in style guides like
Chicago MoS, is towards removing hyphens after prefixes
like "re-" etc.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-01-16 17:45:23 +00:00
|
|
|
and releases the associated resources for reuse.
|
2008-10-10 11:38:11 +00:00
|
|
|
|
2012-04-14 19:06:46 +00:00
|
|
|
.SS epoll_create1()
|
2008-10-10 11:38:11 +00:00
|
|
|
If
|
|
|
|
|
.I flags
|
|
|
|
|
is 0, then, other than the fact that the obsolete
|
2009-02-07 10:55:56 +00:00
|
|
|
.I size
|
2008-10-10 11:38:11 +00:00
|
|
|
argument is dropped,
|
|
|
|
|
.BR epoll_create1 ()
|
|
|
|
|
is the same as
|
|
|
|
|
.BR epoll_create ().
|
|
|
|
|
The following value can be included in
|
|
|
|
|
.IR flags
|
|
|
|
|
to obtain different behavior:
|
|
|
|
|
.TP
|
|
|
|
|
.B EPOLL_CLOEXEC
|
|
|
|
|
Set the close-on-exec
|
2008-10-11 05:34:12 +00:00
|
|
|
.RB ( FD_CLOEXEC )
|
2008-10-10 11:38:11 +00:00
|
|
|
flag on the new file descriptor.
|
2008-10-29 20:43:44 +00:00
|
|
|
See the description of the
|
2008-10-10 11:38:11 +00:00
|
|
|
.B O_CLOEXEC
|
|
|
|
|
flag in
|
|
|
|
|
.BR open (2)
|
|
|
|
|
for reasons why this may be useful.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "RETURN VALUE"
|
2008-10-29 20:43:44 +00:00
|
|
|
On success,
|
2008-10-10 11:38:11 +00:00
|
|
|
these system calls
|
_syscall.2, accept.2, epoll_create.2, inotify_add_watch.2, ioctl.2, msgget.2, msgop.2, open.2, prctl.2, sched_setscheduler.2, semctl.2, semget.2, swapon.2, addseverity.3, cacosh.3, csqrt.3, dirfd.3, drand48.3, fputws.3, mq_send.3, posix_openpt.3, puts.3, sched_getcpu.3, shm_open.3, sqrt.3, sysconf.3, tgamma.3, ulimit.3, credentials.7, svipc.7: Global fix: s/non-negative/nonnegative/
The tendency in English, as prescribed in style guides like
Chicago MoS, is towards removing hyphens after prefixes
like "non-" etc.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-01-16 16:44:48 +00:00
|
|
|
return a nonnegative file descriptor.
|
2008-10-10 11:38:11 +00:00
|
|
|
On error, \-1 is returned, and
|
2004-11-03 13:51:07 +00:00
|
|
|
.I errno
|
2008-10-10 11:38:11 +00:00
|
|
|
is set to indicate the error.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH ERRORS
|
|
|
|
|
.TP
|
2005-04-04 16:33:48 +00:00
|
|
|
.B EINVAL
|
|
|
|
|
.I size
|
|
|
|
|
is not positive.
|
|
|
|
|
.TP
|
2008-10-10 11:38:11 +00:00
|
|
|
.B EINVAL
|
|
|
|
|
.RB ( epoll_create1 ())
|
|
|
|
|
Invalid value specified in
|
|
|
|
|
.IR flags .
|
|
|
|
|
.TP
|
2009-01-16 10:03:08 +00:00
|
|
|
.B EMFILE
|
|
|
|
|
The per-user limit on the number of epoll instances imposed by
|
|
|
|
|
.I /proc/sys/fs/epoll/max_user_instances
|
|
|
|
|
was encountered.
|
|
|
|
|
See
|
|
|
|
|
.BR epoll (7)
|
|
|
|
|
for further details.
|
|
|
|
|
.TP
|
2004-11-03 13:51:07 +00:00
|
|
|
.B ENFILE
|
|
|
|
|
The system limit on the total number of open files has been reached.
|
|
|
|
|
.TP
|
|
|
|
|
.B ENOMEM
|
|
|
|
|
There was insufficient memory to create the kernel object.
|
2010-12-03 06:28:48 +00:00
|
|
|
.SH VERSIONS
|
2007-11-24 10:10:39 +00:00
|
|
|
.BR epoll_create ()
|
2010-12-03 06:28:48 +00:00
|
|
|
was added to the kernel in version 2.6.
|
|
|
|
|
Library support is provided in glibc starting with version 2.3.2.
|
|
|
|
|
|
|
|
|
|
.\" To be precise: kernel 2.5.44.
|
2006-12-17 01:34:44 +00:00
|
|
|
.\" The interface should be finalized by Linux kernel 2.5.66.
|
2010-12-03 06:28:48 +00:00
|
|
|
.BR epoll_create1 ()
|
|
|
|
|
was added to the kernel in version 2.6.27.
|
|
|
|
|
Library support is provided in glibc starting with version 2.9.
|
|
|
|
|
.SH CONFORMING TO
|
|
|
|
|
.BR epoll_create ()
|
|
|
|
|
is Linux-specific.
|
2008-05-17 21:03:05 +00:00
|
|
|
.SH NOTES
|
|
|
|
|
Since Linux 2.6.8, the
|
|
|
|
|
.I size
|
2010-12-03 06:20:28 +00:00
|
|
|
argument is unused, but must be greater than zero.
|
2008-10-10 11:39:46 +00:00
|
|
|
(The kernel dynamically sizes the required data structures
|
|
|
|
|
without needing this initial hint.)
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "SEE ALSO"
|
|
|
|
|
.BR close (2),
|
|
|
|
|
.BR epoll_ctl (2),
|
|
|
|
|
.BR epoll_wait (2),
|
2006-04-21 00:29:37 +00:00
|
|
|
.BR epoll (7)
|
