diff options
Diffstat (limited to 'templates/man7/epoll.7.pot')
| -rw-r--r-- | templates/man7/epoll.7.pot | 974 |
1 files changed, 974 insertions, 0 deletions
diff --git a/templates/man7/epoll.7.pot b/templates/man7/epoll.7.pot new file mode 100644 index 00000000..358b3cac --- /dev/null +++ b/templates/man7/epoll.7.pot @@ -0,0 +1,974 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR Free Software Foundation, Inc. +# This file is distributed under the same license as the PACKAGE package. +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: PACKAGE VERSION\n" +"POT-Creation-Date: 2024-03-01 16:55+0100\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. type: TH +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +#, no-wrap +msgid "epoll" +msgstr "" + +#. type: TH +#: archlinux fedora-40 fedora-rawhide mageia-cauldron +#, no-wrap +msgid "2023-10-31" +msgstr "" + +#. type: TH +#: archlinux fedora-40 fedora-rawhide mageia-cauldron +#, no-wrap +msgid "Linux man-pages 6.06" +msgstr "" + +#. type: SH +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +#, no-wrap +msgid "NAME" +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "epoll - I/O event notification facility" +msgstr "" + +#. type: SH +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +#, no-wrap +msgid "SYNOPSIS" +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +#, no-wrap +msgid "B<#include E<lt>sys/epoll.hE<gt>>\n" +msgstr "" + +#. type: SH +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +#, no-wrap +msgid "DESCRIPTION" +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"The B<epoll> API performs a similar task to B<poll>(2): monitoring multiple " +"file descriptors to see if I/O is possible on any of them. The B<epoll> API " +"can be used either as an edge-triggered or a level-triggered interface and " +"scales well to large numbers of watched file descriptors." +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"The central concept of the B<epoll> API is the B<epoll> I<instance>, an in-" +"kernel data structure which, from a user-space perspective, can be " +"considered as a container for two lists:" +msgstr "" + +#. type: IP +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +#, no-wrap +msgid "\\[bu]" +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"The I<interest> list (sometimes also called the B<epoll> set): the set of " +"file descriptors that the process has registered an interest in monitoring." +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"The I<ready> list: the set of file descriptors that are \"ready\" for I/O. " +"The ready list is a subset of (or, more precisely, a set of references to) " +"the file descriptors in the interest list. The ready list is dynamically " +"populated by the kernel as a result of I/O activity on those file " +"descriptors." +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"The following system calls are provided to create and manage an B<epoll> " +"instance:" +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"B<epoll_create>(2) creates a new B<epoll> instance and returns a file " +"descriptor referring to that instance. (The more recent " +"B<epoll_create1>(2) extends the functionality of B<epoll_create>(2).)" +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"Interest in particular file descriptors is then registered via " +"B<epoll_ctl>(2), which adds items to the interest list of the B<epoll> " +"instance." +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"B<epoll_wait>(2) waits for I/O events, blocking the calling thread if no " +"events are currently available. (This system call can be thought of as " +"fetching items from the ready list of the B<epoll> instance.)" +msgstr "" + +#. type: SS +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +#, no-wrap +msgid "Level-triggered and edge-triggered" +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"The B<epoll> event distribution interface is able to behave both as edge-" +"triggered (ET) and as level-triggered (LT). The difference between the two " +"mechanisms can be described as follows. Suppose that this scenario happens:" +msgstr "" + +#. type: IP +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +#, no-wrap +msgid "(1)" +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"The file descriptor that represents the read side of a pipe (I<rfd>) is " +"registered on the B<epoll> instance." +msgstr "" + +#. type: IP +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +#, no-wrap +msgid "(2)" +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "A pipe writer writes 2\\ kB of data on the write side of the pipe." +msgstr "" + +#. type: IP +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +#, no-wrap +msgid "(3)" +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"A call to B<epoll_wait>(2) is done that will return I<rfd> as a ready file " +"descriptor." +msgstr "" + +#. type: IP +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +#, no-wrap +msgid "(4)" +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "The pipe reader reads 1\\ kB of data from I<rfd>." +msgstr "" + +#. type: IP +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +#, no-wrap +msgid "(5)" +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "A call to B<epoll_wait>(2) is done." +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"If the I<rfd> file descriptor has been added to the B<epoll> interface using " +"the B<EPOLLET> (edge-triggered) flag, the call to B<epoll_wait>(2) done in " +"step B<5> will probably hang despite the available data still present in the " +"file input buffer; meanwhile the remote peer might be expecting a response " +"based on the data it already sent. The reason for this is that edge-" +"triggered mode delivers events only when changes occur on the monitored file " +"descriptor. So, in step B<5> the caller might end up waiting for some data " +"that is already present inside the input buffer. In the above example, an " +"event on I<rfd> will be generated because of the write done in B<2> and the " +"event is consumed in B<3>. Since the read operation done in B<4> does not " +"consume the whole buffer data, the call to B<epoll_wait>(2) done in step " +"B<5> might block indefinitely." +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"An application that employs the B<EPOLLET> flag should use nonblocking file " +"descriptors to avoid having a blocking read or write starve a task that is " +"handling multiple file descriptors. The suggested way to use B<epoll> as an " +"edge-triggered (B<EPOLLET>) interface is as follows:" +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "with nonblocking file descriptors; and" +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"by waiting for an event only after B<read>(2) or B<write>(2) return " +"B<EAGAIN>." +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"By contrast, when used as a level-triggered interface (the default, when " +"B<EPOLLET> is not specified), B<epoll> is simply a faster B<poll>(2), and " +"can be used wherever the latter is used since it shares the same semantics." +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"Since even with edge-triggered B<epoll>, multiple events can be generated " +"upon receipt of multiple chunks of data, the caller has the option to " +"specify the B<EPOLLONESHOT> flag, to tell B<epoll> to disable the associated " +"file descriptor after the receipt of an event with B<epoll_wait>(2). When " +"the B<EPOLLONESHOT> flag is specified, it is the caller's responsibility to " +"rearm the file descriptor using B<epoll_ctl>(2) with B<EPOLL_CTL_MOD>." +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"If multiple threads (or processes, if child processes have inherited the " +"B<epoll> file descriptor across B<fork>(2)) are blocked in " +"B<epoll_wait>(2) waiting on the same epoll file descriptor and a file " +"descriptor in the interest list that is marked for edge-triggered " +"(B<EPOLLET>) notification becomes ready, just one of the threads (or " +"processes) is awoken from B<epoll_wait>(2). This provides a useful " +"optimization for avoiding \"thundering herd\" wake-ups in some scenarios." +msgstr "" + +#. type: SS +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +#, no-wrap +msgid "Interaction with autosleep" +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"If the system is in B<autosleep> mode via I</sys/power/autosleep> and an " +"event happens which wakes the device from sleep, the device driver will keep " +"the device awake only until that event is queued. To keep the device awake " +"until the event has been processed, it is necessary to use the " +"B<epoll_ctl>(2) B<EPOLLWAKEUP> flag." +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"When the B<EPOLLWAKEUP> flag is set in the B<events> field for a I<struct " +"epoll_event>, the system will be kept awake from the moment the event is " +"queued, through the B<epoll_wait>(2) call which returns the event until the " +"subsequent B<epoll_wait>(2) call. If the event should keep the system " +"awake beyond that time, then a separate I<wake_lock> should be taken before " +"the second B<epoll_wait>(2) call." +msgstr "" + +#. type: SS +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +#, no-wrap +msgid "/proc interfaces" +msgstr "" + +#. Following was added in Linux 2.6.28, but them removed in Linux 2.6.29 +#. .TP +#. .IR /proc/sys/fs/epoll/max_user_instances " (since Linux 2.6.28)" +#. This specifies an upper limit on the number of epoll instances +#. that can be created per real user ID. +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"The following interfaces can be used to limit the amount of kernel memory " +"consumed by epoll:" +msgstr "" + +#. type: TP +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +#, no-wrap +msgid "I</proc/sys/fs/epoll/max_user_watches> (since Linux 2.6.28)" +msgstr "" + +#. Linux 2.6.29 (in Linux 2.6.28, the default was 1/32 of lowmem) +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"This specifies a limit on the total number of file descriptors that a user " +"can register across all epoll instances on the system. The limit is per " +"real user ID. Each registered file descriptor costs roughly 90 bytes on a " +"32-bit kernel, and roughly 160 bytes on a 64-bit kernel. Currently, the " +"default value for I<max_user_watches> is 1/25 (4%) of the available low " +"memory, divided by the registration cost in bytes." +msgstr "" + +#. type: SS +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +#, no-wrap +msgid "Example for suggested usage" +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"While the usage of B<epoll> when employed as a level-triggered interface " +"does have the same semantics as B<poll>(2), the edge-triggered usage " +"requires more clarification to avoid stalls in the application event loop. " +"In this example, listener is a nonblocking socket on which B<listen>(2) has " +"been called. The function I<do_use_fd()> uses the new ready file descriptor " +"until B<EAGAIN> is returned by either B<read>(2) or B<write>(2). An event-" +"driven state machine application should, after having received B<EAGAIN>, " +"record its current state so that at the next call to I<do_use_fd()> it will " +"continue to B<read>(2) or B<write>(2) from where it stopped before." +msgstr "" + +#. type: Plain text +#: archlinux debian-unstable fedora-40 fedora-rawhide mageia-cauldron +#: opensuse-tumbleweed +#, no-wrap +msgid "" +"#define MAX_EVENTS 10\n" +"struct epoll_event ev, events[MAX_EVENTS];\n" +"int listen_sock, conn_sock, nfds, epollfd;\n" +"\\&\n" +"/* Code to set up listening socket, \\[aq]listen_sock\\[aq],\n" +" (socket(), bind(), listen()) omitted. */\n" +"\\&\n" +"epollfd = epoll_create1(0);\n" +"if (epollfd == -1) {\n" +" perror(\"epoll_create1\");\n" +" exit(EXIT_FAILURE);\n" +"}\n" +"\\&\n" +"ev.events = EPOLLIN;\n" +"ev.data.fd = listen_sock;\n" +"if (epoll_ctl(epollfd, EPOLL_CTL_ADD, listen_sock, &ev) == -1) {\n" +" perror(\"epoll_ctl: listen_sock\");\n" +" exit(EXIT_FAILURE);\n" +"}\n" +"\\&\n" +"for (;;) {\n" +" nfds = epoll_wait(epollfd, events, MAX_EVENTS, -1);\n" +" if (nfds == -1) {\n" +" perror(\"epoll_wait\");\n" +" exit(EXIT_FAILURE);\n" +" }\n" +"\\&\n" +" for (n = 0; n E<lt> nfds; ++n) {\n" +" if (events[n].data.fd == listen_sock) {\n" +" conn_sock = accept(listen_sock,\n" +" (struct sockaddr *) &addr, &addrlen);\n" +" if (conn_sock == -1) {\n" +" perror(\"accept\");\n" +" exit(EXIT_FAILURE);\n" +" }\n" +" setnonblocking(conn_sock);\n" +" ev.events = EPOLLIN | EPOLLET;\n" +" ev.data.fd = conn_sock;\n" +" if (epoll_ctl(epollfd, EPOLL_CTL_ADD, conn_sock,\n" +" &ev) == -1) {\n" +" perror(\"epoll_ctl: conn_sock\");\n" +" exit(EXIT_FAILURE);\n" +" }\n" +" } else {\n" +" do_use_fd(events[n].data.fd);\n" +" }\n" +" }\n" +"}\n" +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"When used as an edge-triggered interface, for performance reasons, it is " +"possible to add the file descriptor inside the B<epoll> interface " +"(B<EPOLL_CTL_ADD>) once by specifying (B<EPOLLIN>|B<EPOLLOUT>). This " +"allows you to avoid continuously switching between B<EPOLLIN> and " +"B<EPOLLOUT> calling B<epoll_ctl>(2) with B<EPOLL_CTL_MOD>." +msgstr "" + +#. type: SS +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +#, no-wrap +msgid "Questions and answers" +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"What is the key used to distinguish the file descriptors registered in an " +"interest list?" +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"The key is the combination of the file descriptor number and the open file " +"description (also known as an \"open file handle\", the kernel's internal " +"representation of an open file)." +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"What happens if you register the same file descriptor on an B<epoll> " +"instance twice?" +msgstr "" + +# +# +#. But a file descriptor duplicated by fork(2) can't be added to the +#. set, because the [file *, fd] pair is already in the epoll set. +#. That is a somewhat ugly inconsistency. On the one hand, a child process +#. cannot add the duplicate file descriptor to the epoll set. (In every +#. other case that I can think of, file descriptors duplicated by fork have +#. similar semantics to file descriptors duplicated by dup() and friends.) On +#. the other hand, the very fact that the child has a duplicate of the +#. file descriptor means that even if the parent closes its file descriptor, +#. then epoll_wait() in the parent will continue to receive notifications for +#. that file descriptor because of the duplicated file descriptor in the child. +#. See http://thread.gmane.org/gmane.linux.kernel/596462/ +#. "epoll design problems with common fork/exec patterns" +#. mtk, Feb 2008 +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"You will probably get B<EEXIST>. However, it is possible to add a duplicate " +"(B<dup>(2), B<dup2>(2), B<fcntl>(2) B<F_DUPFD>) file descriptor to the " +"same B<epoll> instance. This can be a useful technique for filtering " +"events, if the duplicate file descriptors are registered with different " +"I<events> masks." +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"Can two B<epoll> instances wait for the same file descriptor? If so, are " +"events reported to both B<epoll> file descriptors?" +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"Yes, and events would be reported to both. However, careful programming may " +"be needed to do this correctly." +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "Is the B<epoll> file descriptor itself poll/epoll/selectable?" +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"Yes. If an B<epoll> file descriptor has events waiting, then it will " +"indicate as being readable." +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"What happens if one attempts to put an B<epoll> file descriptor into its own " +"file descriptor set?" +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"The B<epoll_ctl>(2) call fails (B<EINVAL>). However, you can add an " +"B<epoll> file descriptor inside another B<epoll> file descriptor set." +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"Can I send an B<epoll> file descriptor over a UNIX domain socket to another " +"process?" +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"Yes, but it does not make sense to do this, since the receiving process " +"would not have copies of the file descriptors in the interest list." +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"Will closing a file descriptor cause it to be removed from all B<epoll> " +"interest lists?" +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"Yes, but be aware of the following point. A file descriptor is a reference " +"to an open file description (see B<open>(2)). Whenever a file descriptor is " +"duplicated via B<dup>(2), B<dup2>(2), B<fcntl>(2) B<F_DUPFD>, or " +"B<fork>(2), a new file descriptor referring to the same open file " +"description is created. An open file description continues to exist until " +"all file descriptors referring to it have been closed." +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"A file descriptor is removed from an interest list only after all the file " +"descriptors referring to the underlying open file description have been " +"closed. This means that even after a file descriptor that is part of an " +"interest list has been closed, events may be reported for that file " +"descriptor if other file descriptors referring to the same underlying file " +"description remain open. To prevent this happening, the file descriptor " +"must be explicitly removed from the interest list (using B<epoll_ctl>(2) " +"B<EPOLL_CTL_DEL>) before it is duplicated. Alternatively, the application " +"must ensure that all file descriptors are closed (which may be difficult if " +"file descriptors were duplicated behind the scenes by library functions that " +"used B<dup>(2) or B<fork>(2))." +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"If more than one event occurs between B<epoll_wait>(2) calls, are they " +"combined or reported separately?" +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "They will be combined." +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"Does an operation on a file descriptor affect the already collected but not " +"yet reported events?" +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"You can do two operations on an existing file descriptor. Remove would be " +"meaningless for this case. Modify will reread available I/O." +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"Do I need to continuously read/write a file descriptor until B<EAGAIN> when " +"using the B<EPOLLET> flag (edge-triggered behavior)?" +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"Receiving an event from B<epoll_wait>(2) should suggest to you that such " +"file descriptor is ready for the requested I/O operation. You must consider " +"it ready until the next (nonblocking) read/write yields B<EAGAIN>. When " +"and how you will use the file descriptor is entirely up to you." +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"For packet/token-oriented files (e.g., datagram socket, terminal in " +"canonical mode), the only way to detect the end of the read/write I/O space " +"is to continue to read/write until B<EAGAIN>." +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"For stream-oriented files (e.g., pipe, FIFO, stream socket), the condition " +"that the read/write I/O space is exhausted can also be detected by checking " +"the amount of data read from / written to the target file descriptor. For " +"example, if you call B<read>(2) by asking to read a certain amount of data " +"and B<read>(2) returns a lower number of bytes, you can be sure of having " +"exhausted the read I/O space for the file descriptor. The same is true when " +"writing using B<write>(2). (Avoid this latter technique if you cannot " +"guarantee that the monitored file descriptor always refers to a stream-" +"oriented file.)" +msgstr "" + +#. type: SS +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +#, no-wrap +msgid "Possible pitfalls and ways to avoid them" +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "B<Starvation (edge-triggered)>" +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"If there is a large amount of I/O space, it is possible that by trying to " +"drain it the other files will not get processed causing starvation. (This " +"problem is not specific to B<epoll>.)" +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"The solution is to maintain a ready list and mark the file descriptor as " +"ready in its associated data structure, thereby allowing the application to " +"remember which files need to be processed but still round robin amongst all " +"the ready files. This also supports ignoring subsequent events you receive " +"for file descriptors that are already ready." +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "B<If using an event cache...>" +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"If you use an event cache or store all the file descriptors returned from " +"B<epoll_wait>(2), then make sure to provide a way to mark its closure " +"dynamically (i.e., caused by a previous event's processing). Suppose you " +"receive 100 events from B<epoll_wait>(2), and in event #47 a condition " +"causes event #13 to be closed. If you remove the structure and B<close>(2) " +"the file descriptor for event #13, then your event cache might still say " +"there are events waiting for that file descriptor causing confusion." +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"One solution for this is to call, during the processing of event 47, " +"B<epoll_ctl>(B<EPOLL_CTL_DEL>) to delete file descriptor 13 and " +"B<close>(2), then mark its associated data structure as removed and link it " +"to a cleanup list. If you find another event for file descriptor 13 in your " +"batch processing, you will discover the file descriptor had been previously " +"removed and there will be no confusion." +msgstr "" + +#. type: SH +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +#, no-wrap +msgid "VERSIONS" +msgstr "" + +#. type: Plain text +#: archlinux debian-unstable fedora-40 fedora-rawhide mageia-cauldron +#: opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"Some other systems provide similar mechanisms; for example, FreeBSD has " +"I<kqueue>, and Solaris has I</dev/poll>." +msgstr "" + +#. type: SH +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +#, no-wrap +msgid "STANDARDS" +msgstr "" + +#. type: Plain text +#: archlinux debian-unstable fedora-40 fedora-rawhide mageia-cauldron +#: opensuse-leap-15-6 opensuse-tumbleweed +msgid "Linux." +msgstr "" + +#. type: SH +#: archlinux debian-unstable fedora-40 fedora-rawhide mageia-cauldron +#: opensuse-leap-15-6 opensuse-tumbleweed +#, no-wrap +msgid "HISTORY" +msgstr "" + +#. Its interface should be finalized in Linux 2.5.66. +#. type: Plain text +#: archlinux debian-unstable fedora-40 fedora-rawhide mageia-cauldron +#: opensuse-leap-15-6 opensuse-tumbleweed +msgid "Linux 2.5.44. glibc 2.3.2." +msgstr "" + +#. type: SH +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +#, no-wrap +msgid "NOTES" +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"The set of file descriptors that is being monitored via an epoll file " +"descriptor can be viewed via the entry for the epoll file descriptor in the " +"process's I</proc/>pidI</fdinfo> directory. See B<proc>(5) for further " +"details." +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"The B<kcmp>(2) B<KCMP_EPOLL_TFD> operation can be used to test whether a " +"file descriptor is present in an epoll instance." +msgstr "" + +#. type: SH +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +#, no-wrap +msgid "SEE ALSO" +msgstr "" + +#. type: Plain text +#: archlinux debian-bookworm debian-unstable fedora-40 fedora-rawhide +#: mageia-cauldron opensuse-leap-15-6 opensuse-tumbleweed +msgid "" +"B<epoll_create>(2), B<epoll_create1>(2), B<epoll_ctl>(2), B<epoll_wait>(2), " +"B<poll>(2), B<select>(2)" +msgstr "" + +#. type: TH +#: debian-bookworm +#, no-wrap +msgid "2023-02-05" +msgstr "" + +#. type: TH +#: debian-bookworm +#, no-wrap +msgid "Linux man-pages 6.03" +msgstr "" + +#. type: Plain text +#: debian-bookworm opensuse-leap-15-6 +#, no-wrap +msgid "" +"#define MAX_EVENTS 10\n" +"struct epoll_event ev, events[MAX_EVENTS];\n" +"int listen_sock, conn_sock, nfds, epollfd;\n" +msgstr "" + +#. type: Plain text +#: debian-bookworm opensuse-leap-15-6 +#, no-wrap +msgid "" +"/* Code to set up listening socket, \\[aq]listen_sock\\[aq],\n" +" (socket(), bind(), listen()) omitted. */\n" +msgstr "" + +#. type: Plain text +#: debian-bookworm opensuse-leap-15-6 +#, no-wrap +msgid "" +"epollfd = epoll_create1(0);\n" +"if (epollfd == -1) {\n" +" perror(\"epoll_create1\");\n" +" exit(EXIT_FAILURE);\n" +"}\n" +msgstr "" + +#. type: Plain text +#: debian-bookworm opensuse-leap-15-6 +#, no-wrap +msgid "" +"ev.events = EPOLLIN;\n" +"ev.data.fd = listen_sock;\n" +"if (epoll_ctl(epollfd, EPOLL_CTL_ADD, listen_sock, &ev) == -1) {\n" +" perror(\"epoll_ctl: listen_sock\");\n" +" exit(EXIT_FAILURE);\n" +"}\n" +msgstr "" + +#. type: Plain text +#: debian-bookworm opensuse-leap-15-6 +#, no-wrap +msgid "" +"for (;;) {\n" +" nfds = epoll_wait(epollfd, events, MAX_EVENTS, -1);\n" +" if (nfds == -1) {\n" +" perror(\"epoll_wait\");\n" +" exit(EXIT_FAILURE);\n" +" }\n" +msgstr "" + +#. type: Plain text +#: debian-bookworm opensuse-leap-15-6 +#, no-wrap +msgid "" +" for (n = 0; n E<lt> nfds; ++n) {\n" +" if (events[n].data.fd == listen_sock) {\n" +" conn_sock = accept(listen_sock,\n" +" (struct sockaddr *) &addr, &addrlen);\n" +" if (conn_sock == -1) {\n" +" perror(\"accept\");\n" +" exit(EXIT_FAILURE);\n" +" }\n" +" setnonblocking(conn_sock);\n" +" ev.events = EPOLLIN | EPOLLET;\n" +" ev.data.fd = conn_sock;\n" +" if (epoll_ctl(epollfd, EPOLL_CTL_ADD, conn_sock,\n" +" &ev) == -1) {\n" +" perror(\"epoll_ctl: conn_sock\");\n" +" exit(EXIT_FAILURE);\n" +" }\n" +" } else {\n" +" do_use_fd(events[n].data.fd);\n" +" }\n" +" }\n" +"}\n" +msgstr "" + +#. Its interface should be finalized in Linux kernel 2.5.66. +#. type: Plain text +#: debian-bookworm +msgid "" +"The B<epoll> API was introduced in Linux kernel 2.5.44. Support was added " +"in glibc 2.3.2." +msgstr "" + +#. type: Plain text +#: debian-bookworm +msgid "" +"The B<epoll> API is Linux-specific. Some other systems provide similar " +"mechanisms, for example, FreeBSD has I<kqueue>, and Solaris has I</dev/poll>." +msgstr "" + +#. type: TH +#: debian-unstable opensuse-tumbleweed +#, no-wrap +msgid "2023-05-03" +msgstr "" + +#. type: TH +#: debian-unstable opensuse-tumbleweed +#, no-wrap +msgid "Linux man-pages 6.05.01" +msgstr "" + +#. type: TH +#: opensuse-leap-15-6 +#, no-wrap +msgid "2023-03-30" +msgstr "" + +#. type: TH +#: opensuse-leap-15-6 +#, no-wrap +msgid "Linux man-pages 6.04" +msgstr "" |