#, fuzzy msgid "" msgstr "" "Project-Id-Version: man-pages-l10n VERSION\n" "POT-Creation-Date: 2014-07-17 17:57+0900\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" #. type: TH #: man-pages/man7/epoll.7:21 #, no-wrap msgid "EPOLL" msgstr "" #. type: TH #: man-pages/man7/epoll.7:21 #, no-wrap msgid "2014-07-08" msgstr "" #. type: TH #: man-pages/man7/epoll.7:21 #, no-wrap msgid "Linux" msgstr "" #. type: TH #: man-pages/man7/epoll.7:21 #, no-wrap msgid "Linux Programmer's Manual" msgstr "" #. type: SH #: man-pages/man7/epoll.7:22 #, no-wrap msgid "NAME" msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:24 msgid "epoll - I/O event notification facility" msgstr "" #. type: SH #: man-pages/man7/epoll.7:24 #, no-wrap msgid "SYNOPSIS" msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:26 msgid "B<#include Esys/epoll.hE>" msgstr "" #. type: SH #: man-pages/man7/epoll.7:26 #, no-wrap msgid "DESCRIPTION" msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:40 msgid "" "The B API performs a similar task to B(2): monitoring multiple " "file descriptors to see if I/O is possible on any of them. The B API " "can be used either as an edge-triggered or a level-triggered interface and " "scales well to large numbers of watched file descriptors. The following " "system calls are provided to create and manage an B instance:" msgstr "" #. type: IP #: man-pages/man7/epoll.7:40 man-pages/man7/epoll.7:49 man-pages/man7/epoll.7:57 #, no-wrap msgid "*" msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:49 msgid "" "B(2) creates an B instance and returns a file " "descriptor referring to that instance. (The more recent B(2) " " extends the functionality of B(2).)" msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:57 msgid "" "Interest in particular file descriptors is then registered via " "B(2). The set of file descriptors currently registered on an " "B instance is sometimes called an I set." msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:61 msgid "" "B(2) waits for I/O events, blocking the calling thread if no " "events are currently available." msgstr "" #. type: SS #: man-pages/man7/epoll.7:61 #, no-wrap msgid "Level-triggered and edge-triggered" msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:70 msgid "" "The B 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 #: man-pages/man7/epoll.7:70 #, no-wrap msgid "1." msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:76 msgid "" "The file descriptor that represents the read side of a pipe (I) is " "registered on the B instance." msgstr "" #. type: IP #: man-pages/man7/epoll.7:76 #, no-wrap msgid "2." msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:78 msgid "A pipe writer writes 2 kB of data on the write side of the pipe." msgstr "" #. type: IP #: man-pages/man7/epoll.7:78 #, no-wrap msgid "3." msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:84 msgid "" "A call to B(2) is done that will return I as a ready file " "descriptor." msgstr "" #. type: IP #: man-pages/man7/epoll.7:84 #, no-wrap msgid "4." msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:87 msgid "The pipe reader reads 1 kB of data from I." msgstr "" #. type: IP #: man-pages/man7/epoll.7:87 #, no-wrap msgid "5." msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:91 msgid "A call to B(2) is done." msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:126 msgid "" "If the I file descriptor has been added to the B interface using " "the B (edge-triggered) flag, the call to B(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 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(2) done in step " "B<5> might block indefinitely." msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:136 msgid "" "An application that employs the B 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 as an " "edge-triggered (B) interface is as follows:" msgstr "" #. type: TP #: man-pages/man7/epoll.7:137 #, no-wrap msgid "B" msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:140 msgid "with nonblocking file descriptors; and" msgstr "" #. type: TP #: man-pages/man7/epoll.7:140 #, no-wrap msgid "B" msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:148 msgid "" "by waiting for an event only after B(2) or B(2) return " "B." msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:159 msgid "" "By contrast, when used as a level-triggered interface (the default, when " "B is not specified), B is simply a faster B(2), and " "can be used wherever the latter is used since it shares the same semantics." msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:176 msgid "" "Since even with edge-triggered B, multiple events can be generated " "upon receipt of multiple chunks of data, the caller has the option to " "specify the B flag, to tell B to disable the associated " "file descriptor after the receipt of an event with B(2). When " "the B flag is specified, it is the caller's responsibility to " "rearm the file descriptor using B(2) with B." msgstr "" #. type: SS #: man-pages/man7/epoll.7:176 #, no-wrap msgid "Interaction with autosleep" msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:188 msgid "" "If the system is in B mode via I and an " "event happens which wakes the device from sleep, the device driver will only " "keep the device awake until that event is queued. To keep the device awake " "until the event has been processed, it is necessary to use the B(7) " "B flag." msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:207 msgid "" "When the B flag is set in the B field for a I, the system will be kept awake from the moment the event is " "queued, through the B(2) call which returns the event until the " "subsequent B(2) call. If the event should keep the system " "awake beyond that time, then a separate I should be taken before " "the second B(2) call." msgstr "" #. type: SS #: man-pages/man7/epoll.7:207 #, no-wrap msgid "/proc interfaces" msgstr "" #. Following was added in 2.6.28, but them removed in 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 #: man-pages/man7/epoll.7:215 msgid "" "The following interfaces can be used to limit the amount of kernel memory " "consumed by epoll:" msgstr "" #. type: TP #: man-pages/man7/epoll.7:215 #, no-wrap msgid "I (since Linux 2.6.28)" msgstr "" #. 2.6.29 (in 2.6.28, the default was 1/32 of lowmem) #. type: Plain text #: man-pages/man7/epoll.7:229 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 is 1/25 (4%) of the available low " "memory, divided by the registration cost in bytes." msgstr "" #. type: SS #: man-pages/man7/epoll.7:229 #, no-wrap msgid "Example for suggested usage" msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:258 msgid "" "While the usage of B when employed as a level-triggered interface " "does have the same semantics as B(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(2) has " "been called. The function I uses the new ready file descriptor " "until B is returned by either B(2) or B(2). An event-" "driven state machine application should, after having received B, " "record its current state so that at the next call to I it will " "continue to B(2) or B(2) from where it stopped before." msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:264 #, 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 #: man-pages/man7/epoll.7:267 #, no-wrap msgid "" "/* Set up listening socket, \\(aqlisten_sock\\(aq (socket(),\n" " bind(), listen()) */\n" msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:273 #, no-wrap msgid "" "epollfd = epoll_create(10);\n" "if (epollfd == -1) {\n" " perror(\"epoll_create\");\n" " exit(EXIT_FAILURE);\n" "}\n" msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:280 #, 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 #: man-pages/man7/epoll.7:287 #, no-wrap msgid "" "for (;;) {\n" " nfds = epoll_wait(epollfd, events, MAX_EVENTS, -1);\n" " if (nfds == -1) {\n" " perror(\"epoll_pwait\");\n" " exit(EXIT_FAILURE);\n" " }\n" msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:309 #, no-wrap msgid "" " for (n = 0; n E nfds; ++n) {\n" " if (events[n].data.fd == listen_sock) {\n" " conn_sock = accept(listen_sock,\n" " (struct sockaddr *) &local, &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 #: man-pages/man7/epoll.7:328 msgid "" "When used as an edge-triggered interface, for performance reasons, it is " "possible to add the file descriptor inside the B interface " "(B) once by specifying (B|B). This " "allows you to avoid continuously switching between B and " "B calling B(2) with B." msgstr "" #. type: SS #: man-pages/man7/epoll.7:328 #, no-wrap msgid "Questions and answers" msgstr "" #. type: TP #: man-pages/man7/epoll.7:329 #, no-wrap msgid "B" msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:334 msgid "" "What is the key used to distinguish the file descriptors registered in an " "B set?" msgstr "" #. type: TP #: man-pages/man7/epoll.7:334 #, no-wrap msgid "B" msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:340 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: TP #: man-pages/man7/epoll.7:340 #, no-wrap msgid "B" msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:345 msgid "" "What happens if you register the same file descriptor on an B " "instance twice?" msgstr "" #. type: TP #: man-pages/man7/epoll.7:345 #, no-wrap msgid "B" msgstr "" #. But a 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, descriptors duplicated by fork have #. similar semantics to descriptors duplicated by dup() and friends.) On #. the other hand, the very fact that the child has a duplicate of the #. descriptor means that even if the parent closes its descriptor, then #. epoll_wait() in the parent will continue to receive notifications for #. that descriptor because of the duplicated 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 #: man-pages/man7/epoll.7:376 msgid "" "You will probably get B. However, it is possible to add a duplicate " "(B(2), B(2), B(2) B) descriptor to the same " "B instance. This can be a useful technique for filtering events, if " "the duplicate file descriptors are registered with different I masks." "" msgstr "" #. type: TP #: man-pages/man7/epoll.7:376 #, no-wrap msgid "B" msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:384 msgid "" "Can two B instances wait for the same file descriptor? If so, are " "events reported to both B file descriptors?" msgstr "" #. type: TP #: man-pages/man7/epoll.7:384 #, no-wrap msgid "B" msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:388 msgid "" "Yes, and events would be reported to both. However, careful programming may " "be needed to do this correctly." msgstr "" #. type: TP #: man-pages/man7/epoll.7:388 #, no-wrap msgid "B" msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:393 msgid "Is the B file descriptor itself poll/epoll/selectable?" msgstr "" #. type: TP #: man-pages/man7/epoll.7:393 #, no-wrap msgid "B" msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:400 msgid "" "Yes. If an B file descriptor has events waiting, then it will " "indicate as being readable." msgstr "" #. type: TP #: man-pages/man7/epoll.7:400 #, no-wrap msgid "B" msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:405 msgid "" "What happens if one attempts to put an B file descriptor into its own " "file descriptor set?" msgstr "" #. type: TP #: man-pages/man7/epoll.7:405 #, no-wrap msgid "B" msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:416 msgid "" "The B(2) call will fail (B). However, you can add an " "B file descriptor inside another B file descriptor set." msgstr "" #. type: TP #: man-pages/man7/epoll.7:416 #, no-wrap msgid "B" msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:421 msgid "" "Can I send an B file descriptor over a UNIX domain socket to another " "process?" msgstr "" #. type: TP #: man-pages/man7/epoll.7:421 #, no-wrap msgid "B" msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:427 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 B set." msgstr "" #. type: TP #: man-pages/man7/epoll.7:427 #, no-wrap msgid "B" msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:432 msgid "" "Will closing a file descriptor cause it to be removed from all B sets " "automatically?" msgstr "" #. type: TP #: man-pages/man7/epoll.7:432 #, no-wrap msgid "B" msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:460 msgid "" "Yes, but be aware of the following point. A file descriptor is a reference " "to an open file description (see B(2)). Whenever a descriptor is " "duplicated via B(2), B(2), B(2) B, or " "B(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. A file descriptor is " "removed from an B set only after all the file descriptors referring " "to the underlying open file description have been closed (or before if the " "descriptor is explicitly removed using B(2) B). " "This means that even after a file descriptor that is part of an B set " "has been closed, events may be reported for that file descriptor if other " "file descriptors referring to the same underlying file description remain " "open." msgstr "" #. type: TP #: man-pages/man7/epoll.7:460 #, no-wrap msgid "B" msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:465 msgid "" "If more than one event occurs between B(2) calls, are they " "combined or reported separately?" msgstr "" #. type: TP #: man-pages/man7/epoll.7:465 #, no-wrap msgid "B" msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:468 msgid "They will be combined." msgstr "" #. type: TP #: man-pages/man7/epoll.7:468 #, no-wrap msgid "B" msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:472 msgid "" "Does an operation on a file descriptor affect the already collected but not " "yet reported events?" msgstr "" #. type: TP #: man-pages/man7/epoll.7:472 #, no-wrap msgid "B" msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:478 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: TP #: man-pages/man7/epoll.7:478 #, no-wrap msgid "B" msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:486 msgid "" "Do I need to continuously read/write a file descriptor until B when " "using the B flag (edge-triggered behavior) ?" msgstr "" #. type: TP #: man-pages/man7/epoll.7:486 #, no-wrap msgid "B" msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:496 msgid "" "Receiving an event from B(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. When " "and how you will use the file descriptor is entirely up to you." msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:502 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." msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:518 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(2) by asking to read a certain amount of data " "and B(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(2). (Avoid this latter technique if you cannot " "guarantee that the monitored file descriptor always refers to a stream-" "oriented file.)" msgstr "" #. type: SS #: man-pages/man7/epoll.7:518 #, no-wrap msgid "Possible pitfalls and ways to avoid them" msgstr "" #. type: TP #: man-pages/man7/epoll.7:519 #, no-wrap msgid "B" msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:527 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.)" msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:535 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: TP #: man-pages/man7/epoll.7:535 #, no-wrap msgid "B" msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:551 msgid "" "If you use an event cache or store all the file descriptors returned from " "B(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(2), and in event #47 a condition " "causes event #13 to be closed. If you remove the structure and B(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 #: man-pages/man7/epoll.7:562 msgid "" "One solution for this is to call, during the processing of event 47, " "B(B) to delete file descriptor 13 and " "B(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 #: man-pages/man7/epoll.7:562 #, no-wrap msgid "VERSIONS" msgstr "" #. Its interface should be finalized in Linux kernel 2.5.66. #. type: Plain text #: man-pages/man7/epoll.7:568 msgid "" "The B API was introduced in Linux kernel 2.5.44. Support was added " "to glibc in version 2.3.2." msgstr "" #. type: SH #: man-pages/man7/epoll.7:568 #, no-wrap msgid "CONFORMING TO" msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:577 msgid "" "The B API is Linux-specific. Some other systems provide similar " "mechanisms, for example, FreeBSD has I, and Solaris has I." "" msgstr "" #. type: SH #: man-pages/man7/epoll.7:577 #, no-wrap msgid "SEE ALSO" msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:582 msgid "" "B(2), B(2), B(2), B(2)" msgstr "" #. type: SH #: man-pages/man7/epoll.7:582 #, no-wrap msgid "COLOPHON" msgstr "" #. type: Plain text #: man-pages/man7/epoll.7:590 msgid "" "This page is part of release 3.70 of the Linux I project. A " "description of the project, information about reporting bugs, and the latest " "version of this page, can be found at \\%http://www.kernel.org/doc/man-pages/" "." msgstr ""