1 files changed, 144 insertions, 0 deletions
diff --git a/man/man2/epoll_create.2 b/man/man2/epoll_create.2
new file mode 100644
index 000000000..f0327e8ba
--- /dev/null
+++ b/man/man2/epoll_create.2
@@ -0,0 +1,144 @@
+.\"  Copyright (C) 2003  Davide Libenzi
+.\" and Copyright 2008, 2009, 2012 Michael Kerrisk <tk.manpages@gmail.com>
+.\"  Davide Libenzi <davidel@xmailserver.org>
+.\"
+.\" SPDX-License-Identifier: GPL-2.0-or-later
+.\"
+.\" Modified 2004-06-17 by Michael Kerrisk <mtk.manpages@gmail.com>
+.\" Modified 2005-04-04 by Marko Kohtala <marko.kohtala@gmail.com>
+.\" 2008-10-10, mtk: add description of epoll_create1()
+.\"
+.TH epoll_create 2 (date) "Linux man-pages (unreleased)"
+.SH NAME
+epoll_create, epoll_create1 \- open an epoll file descriptor
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <sys/epoll.h>
+.P
+.BI "int epoll_create(int " size );
+.BI "int epoll_create1(int " flags );
+.fi
+.SH DESCRIPTION
+.BR epoll_create ()
+creates a new
+.BR epoll (7)
+instance.
+Since Linux 2.6.8, the
+.I size
+argument is ignored, but must be greater than zero; see HISTORY.
+.P
+.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
+.B epoll
+interface.
+When no longer required, the file descriptor returned by
+.BR epoll_create ()
+should be closed by using
+.BR close (2).
+When all file descriptors referring to an epoll instance have been closed,
+the kernel destroys the instance
+and releases the associated resources for reuse.
+.SS epoll_create1()
+If
+.I flags
+is 0, then, other than the fact that the obsolete
+.I size
+argument is dropped,
+.BR epoll_create1 ()
+is the same as
+.BR epoll_create ().
+The following value can be included in
+.I flags
+to obtain different behavior:
+.TP
+.B EPOLL_CLOEXEC
+Set the close-on-exec
+.RB ( FD_CLOEXEC )
+flag on the new file descriptor.
+See the description of the
+.B O_CLOEXEC
+flag in
+.BR open (2)
+for reasons why this may be useful.
+.SH RETURN VALUE
+On success,
+these system calls
+return a file descriptor (a nonnegative integer).
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EINVAL
+.I size
+is not positive.
+.TP
+.B EINVAL
+.RB ( epoll_create1 ())
+Invalid value specified in
+.IR flags .
+.TP
+.B EMFILE
+The per-process limit on the number of open file descriptors has been reached.
+.TP
+.B ENFILE
+The system-wide limit on the total number of open files has been reached.
+.TP
+.B ENOMEM
+There was insufficient memory to create the kernel object.
+.SH STANDARDS
+Linux.
+.SH HISTORY
+.TP
+.BR epoll_create ()
+Linux 2.6,
+glibc 2.3.2.
+.\" To be precise: kernel 2.5.44.
+.\" The interface should be finalized by Linux kernel 2.5.66.
+.TP
+.BR epoll_create1 ()
+Linux 2.6.27,
+glibc 2.9.
+.P
+In the initial
+.BR epoll_create ()
+implementation, the
+.I size
+argument informed the kernel of the number of file descriptors
+that the caller expected to add to the
+.B epoll
+instance.
+The kernel used this information as a hint for the amount of
+space to initially allocate in internal data structures describing events.
+(If necessary, the kernel would allocate more space
+if the caller's usage exceeded the hint given in
+.IR size .)
+Nowadays,
+this hint is no longer required
+(the kernel dynamically sizes the required data structures
+without needing the hint), but
+.I size
+must still be greater than zero,
+in order to ensure backward compatibility when new
+.B epoll
+applications are run on older kernels.
+.P
+Prior to Linux 2.6.29,
+.\" commit 9df04e1f25effde823a600e755b51475d438f56b
+a
+.I /proc/sys/fs/epoll/max_user_instances
+kernel parameter limited live epolls for each real user ID,
+and caused
+.BR epoll_create ()
+to fail with
+.B EMFILE
+on overrun.
+.SH SEE ALSO
+.BR close (2),
+.BR epoll_ctl (2),
+.BR epoll_wait (2),
+.BR epoll (7)