From 100d1b33f088fd38f69129afff7f9c2a1e084a57 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Fri, 24 May 2024 06:52:24 +0200 Subject: Merging upstream version 6.8. Signed-off-by: Daniel Baumann --- man/man2/epoll_create.2 | 144 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 144 insertions(+) create mode 100644 man/man2/epoll_create.2 (limited to 'man/man2/epoll_create.2') diff --git a/man/man2/epoll_create.2 b/man/man2/epoll_create.2 new file mode 100644 index 0000000..2f73450 --- /dev/null +++ b/man/man2/epoll_create.2 @@ -0,0 +1,144 @@ +.\" Copyright (C) 2003 Davide Libenzi +.\" and Copyright 2008, 2009, 2012 Michael Kerrisk +.\" Davide Libenzi +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified 2004-06-17 by Michael Kerrisk +.\" Modified 2005-04-04 by Marko Kohtala +.\" 2008-10-10, mtk: add description of epoll_create1() +.\" +.TH epoll_create 2 2024-05-02 "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 +.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) -- cgit v1.2.3