1 # SOME DESCRIPTIVE TITLE
2 # Copyright (C) YEAR Free Software Foundation, Inc.
3 # This file is distributed under the same license as the PACKAGE package.
4 # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
9 "Project-Id-Version: PACKAGE VERSION\n"
10 "POT-Creation-Date: 2015-01-23 22:24+0900\n"
11 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
12 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
13 "Language-Team: LANGUAGE <LL@li.org>\n"
16 "Content-Type: text/plain; charset=UTF-8\n"
17 "Content-Transfer-Encoding: 8bit\n"
20 #: build/C/man7/epoll.7:21
26 #: build/C/man7/epoll.7:21
32 #: build/C/man7/epoll.7:21 build/C/man2/epoll_create.2:24 build/C/man2/epoll_ctl.2:20 build/C/man2/epoll_wait.2:22 build/C/man2/poll.2:31
38 #: build/C/man7/epoll.7:21 build/C/man2/epoll_create.2:24 build/C/man2/epoll_ctl.2:20 build/C/man2/epoll_wait.2:22 build/C/man2/poll.2:31
40 msgid "Linux Programmer's Manual"
44 #: build/C/man7/epoll.7:22 build/C/man2/epoll_create.2:25 build/C/man2/epoll_ctl.2:21 build/C/man2/epoll_wait.2:23 build/C/man2/poll.2:32
50 #: build/C/man7/epoll.7:24
51 msgid "epoll - I/O event notification facility"
55 #: build/C/man7/epoll.7:24 build/C/man2/epoll_create.2:27 build/C/man2/epoll_ctl.2:23 build/C/man2/epoll_wait.2:25 build/C/man2/poll.2:34
61 #: build/C/man7/epoll.7:26 build/C/man2/epoll_ctl.2:25
62 msgid "B<#include E<lt>sys/epoll.hE<gt>>"
66 #: build/C/man7/epoll.7:26 build/C/man2/epoll_create.2:34 build/C/man2/epoll_ctl.2:28 build/C/man2/epoll_wait.2:35 build/C/man2/poll.2:47
72 #: build/C/man7/epoll.7:40
74 "The B<epoll> API performs a similar task to B<poll>(2): monitoring multiple "
75 "file descriptors to see if I/O is possible on any of them. The B<epoll> API "
76 "can be used either as an edge-triggered or a level-triggered interface and "
77 "scales well to large numbers of watched file descriptors. The following "
78 "system calls are provided to create and manage an B<epoll> instance:"
82 #: build/C/man7/epoll.7:40 build/C/man7/epoll.7:49 build/C/man7/epoll.7:57 build/C/man2/epoll_wait.2:59 build/C/man2/epoll_wait.2:61 build/C/man2/epoll_wait.2:63 build/C/man2/poll.2:134 build/C/man2/poll.2:136 build/C/man2/poll.2:138
88 #: build/C/man7/epoll.7:49
90 "B<epoll_create>(2) creates an B<epoll> instance and returns a file "
91 "descriptor referring to that instance. (The more recent B<epoll_create1>(2) "
92 "extends the functionality of B<epoll_create>(2).)"
96 #: build/C/man7/epoll.7:57
98 "Interest in particular file descriptors is then registered via "
99 "B<epoll_ctl>(2). The set of file descriptors currently registered on an "
100 "B<epoll> instance is sometimes called an I<epoll> set."
104 #: build/C/man7/epoll.7:61
106 "B<epoll_wait>(2) waits for I/O events, blocking the calling thread if no "
107 "events are currently available."
111 #: build/C/man7/epoll.7:61
113 msgid "Level-triggered and edge-triggered"
117 #: build/C/man7/epoll.7:70
119 "The B<epoll> event distribution interface is able to behave both as "
120 "edge-triggered (ET) and as level-triggered (LT). The difference between the "
121 "two mechanisms can be described as follows. Suppose that this scenario "
126 #: build/C/man7/epoll.7:70
132 #: build/C/man7/epoll.7:76
134 "The file descriptor that represents the read side of a pipe (I<rfd>) is "
135 "registered on the B<epoll> instance."
139 #: build/C/man7/epoll.7:76
145 #: build/C/man7/epoll.7:78
146 msgid "A pipe writer writes 2 kB of data on the write side of the pipe."
150 #: build/C/man7/epoll.7:78
156 #: build/C/man7/epoll.7:84
158 "A call to B<epoll_wait>(2) is done that will return I<rfd> as a ready file "
163 #: build/C/man7/epoll.7:84
169 #: build/C/man7/epoll.7:87
170 msgid "The pipe reader reads 1 kB of data from I<rfd>."
174 #: build/C/man7/epoll.7:87
180 #: build/C/man7/epoll.7:91
181 msgid "A call to B<epoll_wait>(2) is done."
185 #: build/C/man7/epoll.7:126
187 "If the I<rfd> file descriptor has been added to the B<epoll> interface using "
188 "the B<EPOLLET> (edge-triggered) flag, the call to B<epoll_wait>(2) done in "
189 "step B<5> will probably hang despite the available data still present in the "
190 "file input buffer; meanwhile the remote peer might be expecting a response "
191 "based on the data it already sent. The reason for this is that "
192 "edge-triggered mode delivers events only when changes occur on the monitored "
193 "file descriptor. So, in step B<5> the caller might end up waiting for some "
194 "data that is already present inside the input buffer. In the above example, "
195 "an event on I<rfd> will be generated because of the write done in B<2> and "
196 "the event is consumed in B<3>. Since the read operation done in B<4> does "
197 "not consume the whole buffer data, the call to B<epoll_wait>(2) done in "
198 "step B<5> might block indefinitely."
202 #: build/C/man7/epoll.7:136
204 "An application that employs the B<EPOLLET> flag should use nonblocking file "
205 "descriptors to avoid having a blocking read or write starve a task that is "
206 "handling multiple file descriptors. The suggested way to use B<epoll> as an "
207 "edge-triggered (B<EPOLLET>) interface is as follows:"
211 #: build/C/man7/epoll.7:137
217 #: build/C/man7/epoll.7:140
218 msgid "with nonblocking file descriptors; and"
222 #: build/C/man7/epoll.7:140
228 #: build/C/man7/epoll.7:148
230 "by waiting for an event only after B<read>(2) or B<write>(2) return "
235 #: build/C/man7/epoll.7:159
237 "By contrast, when used as a level-triggered interface (the default, when "
238 "B<EPOLLET> is not specified), B<epoll> is simply a faster B<poll>(2), and "
239 "can be used wherever the latter is used since it shares the same semantics."
243 #: build/C/man7/epoll.7:176
245 "Since even with edge-triggered B<epoll>, multiple events can be generated "
246 "upon receipt of multiple chunks of data, the caller has the option to "
247 "specify the B<EPOLLONESHOT> flag, to tell B<epoll> to disable the associated "
248 "file descriptor after the receipt of an event with B<epoll_wait>(2). When "
249 "the B<EPOLLONESHOT> flag is specified, it is the caller's responsibility to "
250 "rearm the file descriptor using B<epoll_ctl>(2) with B<EPOLL_CTL_MOD>."
254 #: build/C/man7/epoll.7:176
256 msgid "Interaction with autosleep"
260 #: build/C/man7/epoll.7:188
262 "If the system is in B<autosleep> mode via I</sys/power/autosleep> and an "
263 "event happens which wakes the device from sleep, the device driver will only "
264 "keep the device awake until that event is queued. To keep the device awake "
265 "until the event has been processed, it is necessary to use the B<epoll>(7) "
266 "B<EPOLLWAKEUP> flag."
270 #: build/C/man7/epoll.7:207
272 "When the B<EPOLLWAKEUP> flag is set in the B<events> field for a I<struct "
273 "epoll_event>, the system will be kept awake from the moment the event is "
274 "queued, through the B<epoll_wait>(2) call which returns the event until the "
275 "subsequent B<epoll_wait>(2) call. If the event should keep the system "
276 "awake beyond that time, then a separate I<wake_lock> should be taken before "
277 "the second B<epoll_wait>(2) call."
281 #: build/C/man7/epoll.7:207
283 msgid "/proc interfaces"
286 #. Following was added in 2.6.28, but them removed in 2.6.29
288 #. .IR /proc/sys/fs/epoll/max_user_instances " (since Linux 2.6.28)"
289 #. This specifies an upper limit on the number of epoll instances
290 #. that can be created per real user ID.
292 #: build/C/man7/epoll.7:215
294 "The following interfaces can be used to limit the amount of kernel memory "
299 #: build/C/man7/epoll.7:215
301 msgid "I</proc/sys/fs/epoll/max_user_watches> (since Linux 2.6.28)"
304 #. 2.6.29 (in 2.6.28, the default was 1/32 of lowmem)
306 #: build/C/man7/epoll.7:229
308 "This specifies a limit on the total number of file descriptors that a user "
309 "can register across all epoll instances on the system. The limit is per "
310 "real user ID. Each registered file descriptor costs roughly 90 bytes on a "
311 "32-bit kernel, and roughly 160 bytes on a 64-bit kernel. Currently, the "
312 "default value for I<max_user_watches> is 1/25 (4%) of the available low "
313 "memory, divided by the registration cost in bytes."
317 #: build/C/man7/epoll.7:229
319 msgid "Example for suggested usage"
323 #: build/C/man7/epoll.7:258
325 "While the usage of B<epoll> when employed as a level-triggered interface "
326 "does have the same semantics as B<poll>(2), the edge-triggered usage "
327 "requires more clarification to avoid stalls in the application event loop. "
328 "In this example, listener is a nonblocking socket on which B<listen>(2) has "
329 "been called. The function I<do_use_fd()> uses the new ready file descriptor "
330 "until B<EAGAIN> is returned by either B<read>(2) or B<write>(2). An "
331 "event-driven state machine application should, after having received "
332 "B<EAGAIN>, record its current state so that at the next call to "
333 "I<do_use_fd()> it will continue to B<read>(2) or B<write>(2) from where it "
338 #: build/C/man7/epoll.7:264
341 "#define MAX_EVENTS 10\n"
342 "struct epoll_event ev, events[MAX_EVENTS];\n"
343 "int listen_sock, conn_sock, nfds, epollfd;\n"
347 #: build/C/man7/epoll.7:267
350 "/* Code to set up listening socket, \\(aqlisten_sock\\(aq,\n"
351 " (socket(), bind(), listen()) omitted */\n"
355 #: build/C/man7/epoll.7:273
358 "epollfd = epoll_create1(0);\n"
359 "if (epollfd == -1) {\n"
360 " perror(\"epoll_create1\");\n"
361 " exit(EXIT_FAILURE);\n"
366 #: build/C/man7/epoll.7:280
369 "ev.events = EPOLLIN;\n"
370 "ev.data.fd = listen_sock;\n"
371 "if (epoll_ctl(epollfd, EPOLL_CTL_ADD, listen_sock, &ev) == -1) {\n"
372 " perror(\"epoll_ctl: listen_sock\");\n"
373 " exit(EXIT_FAILURE);\n"
378 #: build/C/man7/epoll.7:287
382 " nfds = epoll_wait(epollfd, events, MAX_EVENTS, -1);\n"
383 " if (nfds == -1) {\n"
384 " perror(\"epoll_pwait\");\n"
385 " exit(EXIT_FAILURE);\n"
390 #: build/C/man7/epoll.7:309
393 " for (n = 0; n E<lt> nfds; ++n) {\n"
394 " if (events[n].data.fd == listen_sock) {\n"
395 " conn_sock = accept(listen_sock,\n"
396 " (struct sockaddr *) &local, &addrlen);\n"
397 " if (conn_sock == -1) {\n"
398 " perror(\"accept\");\n"
399 " exit(EXIT_FAILURE);\n"
401 " setnonblocking(conn_sock);\n"
402 " ev.events = EPOLLIN | EPOLLET;\n"
403 " ev.data.fd = conn_sock;\n"
404 " if (epoll_ctl(epollfd, EPOLL_CTL_ADD, conn_sock,\n"
406 " perror(\"epoll_ctl: conn_sock\");\n"
407 " exit(EXIT_FAILURE);\n"
410 " do_use_fd(events[n].data.fd);\n"
417 #: build/C/man7/epoll.7:328
419 "When used as an edge-triggered interface, for performance reasons, it is "
420 "possible to add the file descriptor inside the B<epoll> interface "
421 "(B<EPOLL_CTL_ADD>) once by specifying (B<EPOLLIN>|B<EPOLLOUT>). This "
422 "allows you to avoid continuously switching between B<EPOLLIN> and "
423 "B<EPOLLOUT> calling B<epoll_ctl>(2) with B<EPOLL_CTL_MOD>."
427 #: build/C/man7/epoll.7:328
429 msgid "Questions and answers"
433 #: build/C/man7/epoll.7:329
439 #: build/C/man7/epoll.7:334
441 "What is the key used to distinguish the file descriptors registered in an "
446 #: build/C/man7/epoll.7:334
452 #: build/C/man7/epoll.7:340
454 "The key is the combination of the file descriptor number and the open file "
455 "description (also known as an \"open file handle\", the kernel's internal "
456 "representation of an open file)."
460 #: build/C/man7/epoll.7:340
466 #: build/C/man7/epoll.7:345
468 "What happens if you register the same file descriptor on an B<epoll> "
473 #: build/C/man7/epoll.7:345
478 #. But a descriptor duplicated by fork(2) can't be added to the
479 #. set, because the [file *, fd] pair is already in the epoll set.
480 #. That is a somewhat ugly inconsistency. On the one hand, a child process
481 #. cannot add the duplicate file descriptor to the epoll set. (In every
482 #. other case that I can think of, descriptors duplicated by fork have
483 #. similar semantics to descriptors duplicated by dup() and friends.) On
484 #. the other hand, the very fact that the child has a duplicate of the
485 #. descriptor means that even if the parent closes its descriptor, then
486 #. epoll_wait() in the parent will continue to receive notifications for
487 #. that descriptor because of the duplicated descriptor in the child.
489 #. See http://thread.gmane.org/gmane.linux.kernel/596462/
490 #. "epoll design problems with common fork/exec patterns"
494 #: build/C/man7/epoll.7:376
496 "You will probably get B<EEXIST>. However, it is possible to add a duplicate "
497 "(B<dup>(2), B<dup2>(2), B<fcntl>(2) B<F_DUPFD>) descriptor to the same "
498 "B<epoll> instance. This can be a useful technique for filtering events, if "
499 "the duplicate file descriptors are registered with different I<events> "
504 #: build/C/man7/epoll.7:376
510 #: build/C/man7/epoll.7:384
512 "Can two B<epoll> instances wait for the same file descriptor? If so, are "
513 "events reported to both B<epoll> file descriptors?"
517 #: build/C/man7/epoll.7:384
523 #: build/C/man7/epoll.7:388
525 "Yes, and events would be reported to both. However, careful programming may "
526 "be needed to do this correctly."
530 #: build/C/man7/epoll.7:388
536 #: build/C/man7/epoll.7:393
537 msgid "Is the B<epoll> file descriptor itself poll/epoll/selectable?"
541 #: build/C/man7/epoll.7:393
547 #: build/C/man7/epoll.7:400
549 "Yes. If an B<epoll> file descriptor has events waiting, then it will "
550 "indicate as being readable."
554 #: build/C/man7/epoll.7:400
560 #: build/C/man7/epoll.7:405
562 "What happens if one attempts to put an B<epoll> file descriptor into its own "
563 "file descriptor set?"
567 #: build/C/man7/epoll.7:405
573 #: build/C/man7/epoll.7:416
575 "The B<epoll_ctl>(2) call will fail (B<EINVAL>). However, you can add an "
576 "B<epoll> file descriptor inside another B<epoll> file descriptor set."
580 #: build/C/man7/epoll.7:416
586 #: build/C/man7/epoll.7:421
588 "Can I send an B<epoll> file descriptor over a UNIX domain socket to another "
593 #: build/C/man7/epoll.7:421
599 #: build/C/man7/epoll.7:427
601 "Yes, but it does not make sense to do this, since the receiving process "
602 "would not have copies of the file descriptors in the B<epoll> set."
606 #: build/C/man7/epoll.7:427
612 #: build/C/man7/epoll.7:432
614 "Will closing a file descriptor cause it to be removed from all B<epoll> sets "
619 #: build/C/man7/epoll.7:432
625 #: build/C/man7/epoll.7:460
627 "Yes, but be aware of the following point. A file descriptor is a reference "
628 "to an open file description (see B<open>(2)). Whenever a descriptor is "
629 "duplicated via B<dup>(2), B<dup2>(2), B<fcntl>(2) B<F_DUPFD>, or "
630 "B<fork>(2), a new file descriptor referring to the same open file "
631 "description is created. An open file description continues to exist until "
632 "all file descriptors referring to it have been closed. A file descriptor is "
633 "removed from an B<epoll> set only after all the file descriptors referring "
634 "to the underlying open file description have been closed (or before if the "
635 "descriptor is explicitly removed using B<epoll_ctl>(2) B<EPOLL_CTL_DEL>). "
636 "This means that even after a file descriptor that is part of an B<epoll> set "
637 "has been closed, events may be reported for that file descriptor if other "
638 "file descriptors referring to the same underlying file description remain "
643 #: build/C/man7/epoll.7:460
649 #: build/C/man7/epoll.7:465
651 "If more than one event occurs between B<epoll_wait>(2) calls, are they "
652 "combined or reported separately?"
656 #: build/C/man7/epoll.7:465
662 #: build/C/man7/epoll.7:468
663 msgid "They will be combined."
667 #: build/C/man7/epoll.7:468
673 #: build/C/man7/epoll.7:472
675 "Does an operation on a file descriptor affect the already collected but not "
676 "yet reported events?"
680 #: build/C/man7/epoll.7:472
686 #: build/C/man7/epoll.7:478
688 "You can do two operations on an existing file descriptor. Remove would be "
689 "meaningless for this case. Modify will reread available I/O."
693 #: build/C/man7/epoll.7:478
699 #: build/C/man7/epoll.7:486
701 "Do I need to continuously read/write a file descriptor until B<EAGAIN> when "
702 "using the B<EPOLLET> flag (edge-triggered behavior) ?"
706 #: build/C/man7/epoll.7:486
712 #: build/C/man7/epoll.7:496
714 "Receiving an event from B<epoll_wait>(2) should suggest to you that such "
715 "file descriptor is ready for the requested I/O operation. You must consider "
716 "it ready until the next (nonblocking) read/write yields B<EAGAIN>. When "
717 "and how you will use the file descriptor is entirely up to you."
721 #: build/C/man7/epoll.7:502
723 "For packet/token-oriented files (e.g., datagram socket, terminal in "
724 "canonical mode), the only way to detect the end of the read/write I/O space "
725 "is to continue to read/write until B<EAGAIN>."
729 #: build/C/man7/epoll.7:518
731 "For stream-oriented files (e.g., pipe, FIFO, stream socket), the condition "
732 "that the read/write I/O space is exhausted can also be detected by checking "
733 "the amount of data read from / written to the target file descriptor. For "
734 "example, if you call B<read>(2) by asking to read a certain amount of data "
735 "and B<read>(2) returns a lower number of bytes, you can be sure of having "
736 "exhausted the read I/O space for the file descriptor. The same is true when "
737 "writing using B<write>(2). (Avoid this latter technique if you cannot "
738 "guarantee that the monitored file descriptor always refers to a "
739 "stream-oriented file.)"
743 #: build/C/man7/epoll.7:518
745 msgid "Possible pitfalls and ways to avoid them"
749 #: build/C/man7/epoll.7:519
751 msgid "B<o Starvation (edge-triggered)>"
755 #: build/C/man7/epoll.7:527
757 "If there is a large amount of I/O space, it is possible that by trying to "
758 "drain it the other files will not get processed causing starvation. (This "
759 "problem is not specific to B<epoll>.)"
763 #: build/C/man7/epoll.7:535
765 "The solution is to maintain a ready list and mark the file descriptor as "
766 "ready in its associated data structure, thereby allowing the application to "
767 "remember which files need to be processed but still round robin amongst all "
768 "the ready files. This also supports ignoring subsequent events you receive "
769 "for file descriptors that are already ready."
773 #: build/C/man7/epoll.7:535
775 msgid "B<o If using an event cache...>"
779 #: build/C/man7/epoll.7:551
781 "If you use an event cache or store all the file descriptors returned from "
782 "B<epoll_wait>(2), then make sure to provide a way to mark its closure "
783 "dynamically (i.e., caused by a previous event's processing). Suppose you "
784 "receive 100 events from B<epoll_wait>(2), and in event #47 a condition "
785 "causes event #13 to be closed. If you remove the structure and B<close>(2) "
786 "the file descriptor for event #13, then your event cache might still say "
787 "there are events waiting for that file descriptor causing confusion."
791 #: build/C/man7/epoll.7:562
793 "One solution for this is to call, during the processing of event 47, "
794 "B<epoll_ctl>(B<EPOLL_CTL_DEL>) to delete file descriptor 13 and "
795 "B<close>(2), then mark its associated data structure as removed and link it "
796 "to a cleanup list. If you find another event for file descriptor 13 in your "
797 "batch processing, you will discover the file descriptor had been previously "
798 "removed and there will be no confusion."
802 #: build/C/man7/epoll.7:562 build/C/man2/epoll_create.2:108 build/C/man2/epoll_ctl.2:256 build/C/man2/epoll_wait.2:187 build/C/man2/poll.2:330
807 #. Its interface should be finalized in Linux kernel 2.5.66.
809 #: build/C/man7/epoll.7:568
811 "The B<epoll> API was introduced in Linux kernel 2.5.44. Support was added "
812 "to glibc in version 2.3.2."
816 #: build/C/man7/epoll.7:568 build/C/man2/epoll_create.2:118 build/C/man2/epoll_ctl.2:261 build/C/man2/epoll_wait.2:197 build/C/man2/poll.2:347
818 msgid "CONFORMING TO"
822 #: build/C/man7/epoll.7:577
824 "The B<epoll> API is Linux-specific. Some other systems provide similar "
825 "mechanisms, for example, FreeBSD has I<kqueue>, and Solaris has "
830 #: build/C/man7/epoll.7:577 build/C/man2/epoll_create.2:144 build/C/man2/epoll_ctl.2:311 build/C/man2/epoll_wait.2:242 build/C/man2/poll.2:397
836 #: build/C/man7/epoll.7:582
837 msgid "B<epoll_create>(2), B<epoll_create1>(2), B<epoll_ctl>(2), B<epoll_wait>(2)"
841 #: build/C/man7/epoll.7:582 build/C/man2/epoll_create.2:149 build/C/man2/epoll_ctl.2:316 build/C/man2/epoll_wait.2:246 build/C/man2/poll.2:402
847 #: build/C/man7/epoll.7:590 build/C/man2/epoll_create.2:157 build/C/man2/epoll_ctl.2:324 build/C/man2/epoll_wait.2:254 build/C/man2/poll.2:410
849 "This page is part of release 3.78 of the Linux I<man-pages> project. A "
850 "description of the project, information about reporting bugs, and the latest "
851 "version of this page, can be found at "
852 "\\%http://www.kernel.org/doc/man-pages/."
856 #: build/C/man2/epoll_create.2:24
862 #: build/C/man2/epoll_create.2:24
868 #: build/C/man2/epoll_create.2:27
869 msgid "epoll_create, epoll_create1 - open an epoll file descriptor"
873 #: build/C/man2/epoll_create.2:30 build/C/man2/epoll_wait.2:28
875 msgid "B<#include E<lt>sys/epoll.hE<gt>>\n"
879 #: build/C/man2/epoll_create.2:33
882 "B<int epoll_create(int >I<size>B<);>\n"
883 "B<int epoll_create1(int >I<flags>B<);>\n"
887 #: build/C/man2/epoll_create.2:42
889 "B<epoll_create>() creates an B<epoll>(7) instance. Since Linux 2.6.8, the "
890 "I<size> argument is ignored, but must be greater than zero; see NOTES below."
894 #: build/C/man2/epoll_create.2:55
896 "B<epoll_create>() returns a file descriptor referring to the new epoll "
897 "instance. This file descriptor is used for all the subsequent calls to the "
898 "B<epoll> interface. When no longer required, the file descriptor returned "
899 "by B<epoll_create>() should be closed by using B<close>(2). When all file "
900 "descriptors referring to an epoll instance have been closed, the kernel "
901 "destroys the instance and releases the associated resources for reuse."
905 #: build/C/man2/epoll_create.2:55
907 msgid "epoll_create1()"
911 #: build/C/man2/epoll_create.2:67
913 "If I<flags> is 0, then, other than the fact that the obsolete I<size> "
914 "argument is dropped, B<epoll_create1>() is the same as B<epoll_create>(). "
915 "The following value can be included in I<flags> to obtain different "
920 #: build/C/man2/epoll_create.2:67
922 msgid "B<EPOLL_CLOEXEC>"
926 #: build/C/man2/epoll_create.2:77
928 "Set the close-on-exec (B<FD_CLOEXEC>) flag on the new file descriptor. See "
929 "the description of the B<O_CLOEXEC> flag in B<open>(2) for reasons why this "
934 #: build/C/man2/epoll_create.2:77 build/C/man2/epoll_ctl.2:185 build/C/man2/epoll_wait.2:150 build/C/man2/poll.2:301
940 #: build/C/man2/epoll_create.2:84
942 "On success, these system calls return a nonnegative file descriptor. On "
943 "error, -1 is returned, and I<errno> is set to indicate the error."
947 #: build/C/man2/epoll_create.2:84 build/C/man2/epoll_ctl.2:194 build/C/man2/epoll_wait.2:162 build/C/man2/poll.2:311
953 #: build/C/man2/epoll_create.2:85 build/C/man2/epoll_create.2:89 build/C/man2/epoll_ctl.2:209 build/C/man2/epoll_wait.2:179 build/C/man2/poll.2:320
959 #: build/C/man2/epoll_create.2:89
960 msgid "I<size> is not positive."
964 #: build/C/man2/epoll_create.2:94
965 msgid "(B<epoll_create1>()) Invalid value specified in I<flags>."
969 #: build/C/man2/epoll_create.2:94
975 #: build/C/man2/epoll_create.2:102
977 "The per-user limit on the number of epoll instances imposed by "
978 "I</proc/sys/fs/epoll/max_user_instances> was encountered. See B<epoll>(7) "
979 "for further details."
983 #: build/C/man2/epoll_create.2:102
989 #: build/C/man2/epoll_create.2:105
990 msgid "The system limit on the total number of open files has been reached."
994 #: build/C/man2/epoll_create.2:105 build/C/man2/epoll_ctl.2:232 build/C/man2/poll.2:327
1000 #: build/C/man2/epoll_create.2:108
1001 msgid "There was insufficient memory to create the kernel object."
1005 #: build/C/man2/epoll_create.2:112
1007 "B<epoll_create>() was added to the kernel in version 2.6. Library support "
1008 "is provided in glibc starting with version 2.3.2."
1011 #. To be precise: kernel 2.5.44.
1012 #. The interface should be finalized by Linux kernel 2.5.66.
1014 #: build/C/man2/epoll_create.2:118
1016 "B<epoll_create1>() was added to the kernel in version 2.6.27. Library "
1017 "support is provided in glibc starting with version 2.9."
1021 #: build/C/man2/epoll_create.2:121
1022 msgid "B<epoll_create>() is Linux-specific."
1026 #: build/C/man2/epoll_create.2:121 build/C/man2/epoll_ctl.2:265 build/C/man2/epoll_wait.2:200 build/C/man2/poll.2:353
1032 #: build/C/man2/epoll_create.2:144
1034 "In the initial B<epoll_create>() implementation, the I<size> argument "
1035 "informed the kernel of the number of file descriptors that the caller "
1036 "expected to add to the B<epoll> instance. The kernel used this information "
1037 "as a hint for the amount of space to initially allocate in internal data "
1038 "structures describing events. (If necessary, the kernel would allocate more "
1039 "space if the caller's usage exceeded the hint given in I<size>.) Nowadays, "
1040 "this hint is no longer required (the kernel dynamically sizes the required "
1041 "data structures without needing the hint), but I<size> must still be greater "
1042 "than zero, in order to ensure backward compatibility when new B<epoll> "
1043 "applications are run on older kernels."
1047 #: build/C/man2/epoll_create.2:149
1048 msgid "B<close>(2), B<epoll_ctl>(2), B<epoll_wait>(2), B<epoll>(7)"
1052 #: build/C/man2/epoll_ctl.2:20
1058 #: build/C/man2/epoll_ctl.2:20
1064 #: build/C/man2/epoll_ctl.2:23
1065 msgid "epoll_ctl - control interface for an epoll descriptor"
1069 #: build/C/man2/epoll_ctl.2:28
1071 "B<int epoll_ctl(int >I<epfd>B<, int >I<op>B<, int >I<fd>B<, struct "
1072 "epoll_event *>I<event>B<);>"
1076 #: build/C/man2/epoll_ctl.2:38
1078 "This system call performs control operations on the B<epoll>(7) instance "
1079 "referred to by the file descriptor I<epfd>. It requests that the operation "
1080 "I<op> be performed for the target file descriptor, I<fd>."
1084 #: build/C/man2/epoll_ctl.2:42
1085 msgid "Valid values for the I<op> argument are:"
1089 #: build/C/man2/epoll_ctl.2:42
1091 msgid "B<EPOLL_CTL_ADD>"
1095 #: build/C/man2/epoll_ctl.2:54
1097 "Register the target file descriptor I<fd> on the B<epoll> instance referred "
1098 "to by the file descriptor I<epfd> and associate the event I<event> with the "
1099 "internal file linked to I<fd>."
1103 #: build/C/man2/epoll_ctl.2:54
1105 msgid "B<EPOLL_CTL_MOD>"
1109 #: build/C/man2/epoll_ctl.2:60
1110 msgid "Change the event I<event> associated with the target file descriptor I<fd>."
1114 #: build/C/man2/epoll_ctl.2:60
1116 msgid "B<EPOLL_CTL_DEL>"
1120 #: build/C/man2/epoll_ctl.2:71
1122 "Remove (deregister) the target file descriptor I<fd> from the B<epoll> "
1123 "instance referred to by I<epfd>. The I<event> is ignored and can be NULL "
1124 "(but see BUGS below)."
1128 #: build/C/man2/epoll_ctl.2:79
1130 "The I<event> argument describes the object linked to the file descriptor "
1131 "I<fd>. The I<struct epoll_event> is defined as:"
1135 #: build/C/man2/epoll_ctl.2:88
1138 "typedef union epoll_data {\n"
1147 #: build/C/man2/epoll_ctl.2:93
1150 "struct epoll_event {\n"
1151 " uint32_t events; /* Epoll events */\n"
1152 " epoll_data_t data; /* User data variable */\n"
1157 #: build/C/man2/epoll_ctl.2:100
1159 "The I<events> member is a bit set composed using the following available "
1164 #: build/C/man2/epoll_ctl.2:100
1170 #: build/C/man2/epoll_ctl.2:105
1171 msgid "The associated file is available for B<read>(2) operations."
1175 #: build/C/man2/epoll_ctl.2:105
1181 #: build/C/man2/epoll_ctl.2:110
1182 msgid "The associated file is available for B<write>(2) operations."
1186 #: build/C/man2/epoll_ctl.2:110
1188 msgid "B<EPOLLRDHUP> (since Linux 2.6.17)"
1192 #: build/C/man2/epoll_ctl.2:116
1194 "Stream socket peer closed connection, or shut down writing half of "
1195 "connection. (This flag is especially useful for writing simple code to "
1196 "detect peer shutdown when using Edge Triggered monitoring.)"
1200 #: build/C/man2/epoll_ctl.2:116
1206 #: build/C/man2/epoll_ctl.2:121
1207 msgid "There is urgent data available for B<read>(2) operations."
1211 #: build/C/man2/epoll_ctl.2:121
1217 #: build/C/man2/epoll_ctl.2:127
1219 "Error condition happened on the associated file descriptor. "
1220 "B<epoll_wait>(2) will always wait for this event; it is not necessary to "
1221 "set it in I<events>."
1225 #: build/C/man2/epoll_ctl.2:127
1231 #: build/C/man2/epoll_ctl.2:133
1233 "Hang up happened on the associated file descriptor. B<epoll_wait>(2) will "
1234 "always wait for this event; it is not necessary to set it in I<events>."
1238 #: build/C/man2/epoll_ctl.2:133
1244 #: build/C/man2/epoll_ctl.2:143
1246 "Sets the Edge Triggered behavior for the associated file descriptor. The "
1247 "default behavior for B<epoll> is Level Triggered. See B<epoll>(7) for more "
1248 "detailed information about Edge and Level Triggered event distribution "
1253 #: build/C/man2/epoll_ctl.2:143
1255 msgid "B<EPOLLONESHOT> (since Linux 2.6.2)"
1259 #: build/C/man2/epoll_ctl.2:157
1261 "Sets the one-shot behavior for the associated file descriptor. This means "
1262 "that after an event is pulled out with B<epoll_wait>(2) the associated file "
1263 "descriptor is internally disabled and no other events will be reported by "
1264 "the B<epoll> interface. The user must call B<epoll_ctl>() with "
1265 "B<EPOLL_CTL_MOD> to rearm the file descriptor with a new event mask."
1269 #: build/C/man2/epoll_ctl.2:157
1271 msgid "B<EPOLLWAKEUP> (since Linux 3.5)"
1274 #. commit 4d7e30d98939a0340022ccd49325a3d70f7e0238
1276 #: build/C/man2/epoll_ctl.2:185
1278 "If B<EPOLLONESHOT> and B<EPOLLET> are clear and the process has the "
1279 "B<CAP_BLOCK_SUSPEND> capability, ensure that the system does not enter "
1280 "\"suspend\" or \"hibernate\" while this event is pending or being "
1281 "processed. The event is considered as being \"processed\" from the time "
1282 "when it is returned by a call to B<epoll_wait>(2) until the next call to "
1283 "B<epoll_wait>(2) on the same B<epoll>(7) file descriptor, the closure of "
1284 "that file descriptor, the removal of the event file descriptor with "
1285 "B<EPOLL_CTL_DEL>, or the clearing of B<EPOLLWAKEUP> for the event file "
1286 "descriptor with B<EPOLL_CTL_MOD>. See also BUGS."
1290 #: build/C/man2/epoll_ctl.2:194
1292 "When successful, B<epoll_ctl>() returns zero. When an error occurs, "
1293 "B<epoll_ctl>() returns -1 and I<errno> is set appropriately."
1297 #: build/C/man2/epoll_ctl.2:195 build/C/man2/epoll_wait.2:163
1303 #: build/C/man2/epoll_ctl.2:201
1304 msgid "I<epfd> or I<fd> is not a valid file descriptor."
1308 #: build/C/man2/epoll_ctl.2:201
1314 #: build/C/man2/epoll_ctl.2:209
1316 "I<op> was B<EPOLL_CTL_ADD>, and the supplied file descriptor I<fd> is "
1317 "already registered with this epoll instance."
1321 #: build/C/man2/epoll_ctl.2:222
1323 "I<epfd> is not an B<epoll> file descriptor, or I<fd> is the same as I<epfd>, "
1324 "or the requested operation I<op> is not supported by this interface."
1328 #: build/C/man2/epoll_ctl.2:222
1334 #: build/C/man2/epoll_ctl.2:232
1336 "I<op> was B<EPOLL_CTL_MOD> or B<EPOLL_CTL_DEL>, and I<fd> is not registered "
1337 "with this epoll instance."
1341 #: build/C/man2/epoll_ctl.2:237
1343 "There was insufficient memory to handle the requested I<op> control "
1348 #: build/C/man2/epoll_ctl.2:237
1354 #: build/C/man2/epoll_ctl.2:247
1356 "The limit imposed by I</proc/sys/fs/epoll/max_user_watches> was encountered "
1357 "while trying to register (B<EPOLL_CTL_ADD>) a new file descriptor on an "
1358 "epoll instance. See B<epoll>(7) for further details."
1362 #: build/C/man2/epoll_ctl.2:247
1368 #: build/C/man2/epoll_ctl.2:256
1370 "The target file I<fd> does not support B<epoll>. This error can occur if "
1371 "I<fd> refers to, for example, a regular file or a directory."
1374 #. To be precise: kernel 2.5.44.
1375 #. The interface should be finalized by Linux kernel 2.5.66.
1377 #: build/C/man2/epoll_ctl.2:261
1378 msgid "B<epoll_ctl>() was added to the kernel in version 2.6."
1382 #: build/C/man2/epoll_ctl.2:265
1384 "B<epoll_ctl>() is Linux-specific. Library support is provided in glibc "
1385 "starting with version 2.3.2."
1389 #: build/C/man2/epoll_ctl.2:270
1391 "The B<epoll> interface supports all file descriptors that support "
1396 #: build/C/man2/epoll_ctl.2:270 build/C/man2/epoll_wait.2:217 build/C/man2/poll.2:393
1402 #: build/C/man2/epoll_ctl.2:284
1404 "In kernel versions before 2.6.9, the B<EPOLL_CTL_DEL> operation required a "
1405 "non-null pointer in I<event>, even though this argument is ignored. Since "
1406 "Linux 2.6.9, I<event> can be specified as NULL when using B<EPOLL_CTL_DEL>. "
1407 "Applications that need to be portable to kernels before 2.6.9 should specify "
1408 "a non-null pointer in I<event>."
1411 #. commit a8159414d7e3af7233e7a5a82d1c5d85379bd75c (behavior change)
1412 #. https://lwn.net/Articles/520198/
1414 #: build/C/man2/epoll_ctl.2:311
1416 "If B<EPOLLWAKEUP> is specified in I<flags>, but the caller does not have the "
1417 "B<CAP_BLOCK_SUSPEND> capability, then the B<EPOLLWAKEUP> flag is I<silently "
1418 "ignored>. This unfortunate behavior is necessary because no validity checks "
1419 "were performed on the I<flags> argument in the original implementation, and "
1420 "the addition of the B<EPOLLWAKEUP> with a check that caused the call to fail "
1421 "if the caller did not have the B<CAP_BLOCK_SUSPEND> capability caused a "
1422 "breakage in at least one existing user-space application that happened to "
1423 "randomly (and uselessly) specify this bit. A robust application should "
1424 "therefore double check that it has the B<CAP_BLOCK_SUSPEND> capability if "
1425 "attempting to use the B<EPOLLWAKEUP> flag."
1429 #: build/C/man2/epoll_ctl.2:316
1430 msgid "B<epoll_create>(2), B<epoll_wait>(2), B<poll>(2), B<epoll>(7)"
1434 #: build/C/man2/epoll_wait.2:22
1440 #: build/C/man2/epoll_wait.2:22
1446 #: build/C/man2/epoll_wait.2:25
1447 msgid "epoll_wait, epoll_pwait - wait for an I/O event on an epoll file descriptor"
1451 #: build/C/man2/epoll_wait.2:34
1454 "B<int epoll_wait(int >I<epfd>B<, struct epoll_event *>I<events>B<,>\n"
1455 "B< int >I<maxevents>B<, int >I<timeout>B<);>\n"
1456 "B<int epoll_pwait(int >I<epfd>B<, struct epoll_event *>I<events>B<,>\n"
1457 "B< int >I<maxevents>B<, int >I<timeout>B<,>\n"
1458 "B< const sigset_t *>I<sigmask>B<);>\n"
1462 #: build/C/man2/epoll_wait.2:52
1464 "The B<epoll_wait>() system call waits for events on the B<epoll>(7) "
1465 "instance referred to by the file descriptor I<epfd>. The memory area "
1466 "pointed to by I<events> will contain the events that will be available for "
1467 "the caller. Up to I<maxevents> are returned by B<epoll_wait>(). The "
1468 "I<maxevents> argument must be greater than zero."
1472 #: build/C/man2/epoll_wait.2:59
1474 "The I<timeout> argument specifies the number of milliseconds that "
1475 "B<epoll_wait>() will block. The call will block until either:"
1479 #: build/C/man2/epoll_wait.2:61
1480 msgid "a file descriptor delivers an event;"
1484 #: build/C/man2/epoll_wait.2:63 build/C/man2/poll.2:138
1485 msgid "the call is interrupted by a signal handler; or"
1489 #: build/C/man2/epoll_wait.2:65 build/C/man2/poll.2:140
1490 msgid "the timeout expires."
1494 #: build/C/man2/epoll_wait.2:80
1496 "Note that the I<timeout> interval will be rounded up to the system clock "
1497 "granularity, and kernel scheduling delays mean that the blocking interval "
1498 "may overrun by a small amount. Specifying a I<timeout> of -1 causes "
1499 "B<epoll_wait>() to block indefinitely, while specifying a I<timeout> equal "
1500 "to zero cause B<epoll_wait>() to return immediately, even if no events are "
1505 #: build/C/man2/epoll_wait.2:84
1506 msgid "The I<struct epoll_event> is defined as:"
1510 #: build/C/man2/epoll_wait.2:93
1513 "typedef union epoll_data {\n"
1522 #: build/C/man2/epoll_wait.2:98
1525 "struct epoll_event {\n"
1526 " uint32_t events; /* Epoll events */\n"
1527 " epoll_data_t data; /* User data variable */\n"
1532 #: build/C/man2/epoll_wait.2:109
1534 "The I<data> of each returned structure will contain the same data the user "
1535 "set with an B<epoll_ctl>(2) (B<EPOLL_CTL_ADD>, B<EPOLL_CTL_MOD>) while the "
1536 "I<events> member will contain the returned event bit field."
1540 #: build/C/man2/epoll_wait.2:109
1542 msgid "epoll_pwait()"
1546 #: build/C/man2/epoll_wait.2:123
1548 "The relationship between B<epoll_wait>() and B<epoll_pwait>() is analogous "
1549 "to the relationship between B<select>(2) and B<pselect>(2): like "
1550 "B<pselect>(2), B<epoll_pwait>() allows an application to safely wait until "
1551 "either a file descriptor becomes ready or until a signal is caught."
1555 #: build/C/man2/epoll_wait.2:127
1556 msgid "The following B<epoll_pwait>() call:"
1560 #: build/C/man2/epoll_wait.2:130
1562 msgid " ready = epoll_pwait(epfd, &events, maxevents, timeout, &sigmask);\n"
1566 #: build/C/man2/epoll_wait.2:135 build/C/man2/poll.2:250
1567 msgid "is equivalent to I<atomically> executing the following calls:"
1571 #: build/C/man2/epoll_wait.2:138
1573 msgid " sigset_t origmask;\n"
1577 #: build/C/man2/epoll_wait.2:142
1580 " sigprocmask(SIG_SETMASK, &sigmask, &origmask);\n"
1581 " ready = epoll_wait(epfd, &events, maxevents, timeout);\n"
1582 " sigprocmask(SIG_SETMASK, &origmask, NULL);\n"
1586 #: build/C/man2/epoll_wait.2:150
1588 "The I<sigmask> argument may be specified as NULL, in which case "
1589 "B<epoll_pwait>() is equivalent to B<epoll_wait>()."
1593 #: build/C/man2/epoll_wait.2:162
1595 "When successful, B<epoll_wait>() returns the number of file descriptors "
1596 "ready for the requested I/O, or zero if no file descriptor became ready "
1597 "during the requested I<timeout> milliseconds. When an error occurs, "
1598 "B<epoll_wait>() returns -1 and I<errno> is set appropriately."
1602 #: build/C/man2/epoll_wait.2:167
1603 msgid "I<epfd> is not a valid file descriptor."
1607 #: build/C/man2/epoll_wait.2:167 build/C/man2/poll.2:312
1613 #: build/C/man2/epoll_wait.2:172
1615 "The memory area pointed to by I<events> is not accessible with write "
1620 #: build/C/man2/epoll_wait.2:172 build/C/man2/poll.2:316
1626 #: build/C/man2/epoll_wait.2:179
1628 "The call was interrupted by a signal handler before either (1) any of the "
1629 "requested events occurred or (2) the I<timeout> expired; see B<signal>(7)."
1633 #: build/C/man2/epoll_wait.2:187
1635 "I<epfd> is not an B<epoll> file descriptor, or I<maxevents> is less than or "
1639 #. To be precise: kernel 2.5.44.
1640 #. The interface should be finalized by Linux kernel 2.5.66.
1642 #: build/C/man2/epoll_wait.2:193
1644 "B<epoll_wait>() was added to the kernel in version 2.6. Library support is "
1645 "provided in glibc starting with version 2.3.2."
1649 #: build/C/man2/epoll_wait.2:197
1651 "B<epoll_pwait>() was added to Linux in kernel 2.6.19. Library support is "
1652 "provided in glibc starting with version 2.6."
1656 #: build/C/man2/epoll_wait.2:200
1657 msgid "B<epoll_wait>() is Linux-specific."
1661 #: build/C/man2/epoll_wait.2:210
1663 "While one thread is blocked in a call to B<epoll_pwait>(), it is possible "
1664 "for another thread to add a file descriptor to the waited-upon B<epoll> "
1665 "instance. If the new file descriptor becomes ready, it will cause the "
1666 "B<epoll_wait>() call to unblock."
1670 #: build/C/man2/epoll_wait.2:217
1672 "For a discussion of what may happen if a file descriptor in an B<epoll> "
1673 "instance being monitored by B<epoll_wait>() is closed in another thread, "
1678 #: build/C/man2/epoll_wait.2:229
1680 "In kernels before 2.6.37, a I<timeout> value larger than approximately "
1681 "I<LONG_MAX / HZ> milliseconds is treated as -1 (i.e., infinity). Thus, for "
1682 "example, on a system where the I<sizeof(long)> is 4 and the kernel I<HZ> "
1683 "value is 1000, this means that timeouts greater than 35.79 minutes are "
1684 "treated as infinity."
1688 #: build/C/man2/epoll_wait.2:229 build/C/man2/poll.2:366
1690 msgid "C library/kernel ABI differences"
1694 #: build/C/man2/epoll_wait.2:242
1696 "The raw B<epoll_pwait>() system call has a sixth argument, I<size_t "
1697 "sigsetsize>, which specifies the size in bytes of the I<sigmask> argument. "
1698 "The glibc B<epoll_pwait>() wrapper function specifies this argument as a "
1699 "fixed value (equal to I<sizeof(sigset_t)>)."
1703 #: build/C/man2/epoll_wait.2:246
1704 msgid "B<epoll_create>(2), B<epoll_ctl>(2), B<epoll>(7)"
1708 #: build/C/man2/poll.2:31
1714 #: build/C/man2/poll.2:31
1720 #: build/C/man2/poll.2:34
1721 msgid "poll, ppoll - wait for some event on a file descriptor"
1725 #: build/C/man2/poll.2:37
1727 msgid "B<#include E<lt>poll.hE<gt>>\n"
1731 #: build/C/man2/poll.2:39
1734 "B<int poll(struct pollfd *>I<fds>B<, nfds_t >I<nfds>B<, int "
1735 ">I<timeout>B<);>\n"
1739 #: build/C/man2/poll.2:43
1742 "B<#define _GNU_SOURCE> /* See feature_test_macros(7) */\n"
1743 "B<#include E<lt>signal.hE<gt>>\n"
1744 "B<#include E<lt>poll.hE<gt>>\n"
1748 #: build/C/man2/poll.2:46
1751 "B<int ppoll(struct pollfd *>I<fds>B<, nfds_t >I<nfds>B<, >\n"
1752 "B< const struct timespec *>I<timeout_ts>B<, const sigset_t "
1753 "*>I<sigmask>B<);>\n"
1757 #: build/C/man2/poll.2:53
1759 "B<poll>() performs a similar task to B<select>(2): it waits for one of a "
1760 "set of file descriptors to become ready to perform I/O."
1764 #: build/C/man2/poll.2:57
1766 "The set of file descriptors to be monitored is specified in the I<fds> "
1767 "argument, which is an array of structures of the following form:"
1771 #: build/C/man2/poll.2:65
1775 " int fd; /* file descriptor */\n"
1776 " short events; /* requested events */\n"
1777 " short revents; /* returned events */\n"
1782 #: build/C/man2/poll.2:72
1784 "The caller should specify the number of items in the I<fds> array in "
1789 #: build/C/man2/poll.2:88
1791 "The field I<fd> contains a file descriptor for an open file. If this field "
1792 "is negative, then the corresponding I<events> field is ignored and the "
1793 "I<revents> field returns zero. (This provides an easy way of ignoring a "
1794 "file descriptor for a single B<poll>() call: simply negate the I<fd> "
1795 "field. Note, however, that this technique can't be used to ignore file "
1800 #: build/C/man2/poll.2:103
1802 "The field I<events> is an input parameter, a bit mask specifying the events "
1803 "the application is interested in for the file descriptor I<fd>. This field "
1804 "may be specified as zero, in which case the only events that can be returned "
1805 "in I<revents> are B<POLLHUP>, B<POLLERR>, and B<POLLNVAL> (see below)."
1809 #: build/C/man2/poll.2:122
1811 "The field I<revents> is an output parameter, filled by the kernel with the "
1812 "events that actually occurred. The bits returned in I<revents> can include "
1813 "any of those specified in I<events>, or one of the values B<POLLERR>, "
1814 "B<POLLHUP>, or B<POLLNVAL>. (These three bits are meaningless in the "
1815 "I<events> field, and will be set in the I<revents> field whenever the "
1816 "corresponding condition is true.)"
1820 #: build/C/man2/poll.2:127
1822 "If none of the events requested (and no error) has occurred for any of the "
1823 "file descriptors, then B<poll>() blocks until one of the events occurs."
1827 #: build/C/man2/poll.2:134
1829 "The I<timeout> argument specifies the number of milliseconds that B<poll>() "
1830 "should block waiting for a file descriptor to become ready. The call will "
1831 "block until either:"
1835 #: build/C/man2/poll.2:136
1836 msgid "a file descriptor becomes ready;"
1840 #: build/C/man2/poll.2:154
1842 "Note that the I<timeout> interval will be rounded up to the system clock "
1843 "granularity, and kernel scheduling delays mean that the blocking interval "
1844 "may overrun by a small amount. Specifying a negative value in I<timeout> "
1845 "means an infinite timeout. Specifying a I<timeout> of zero causes B<poll>() "
1846 "to return immediately, even if no file descriptors are ready."
1850 #: build/C/man2/poll.2:160
1852 "The bits that may be set/returned in I<events> and I<revents> are defined in "
1853 "I<E<lt>poll.hE<gt>>:"
1857 #: build/C/man2/poll.2:161
1863 #: build/C/man2/poll.2:164
1864 msgid "There is data to read."
1868 #: build/C/man2/poll.2:164
1874 #: build/C/man2/poll.2:168
1876 "There is urgent data to read (e.g., out-of-band data on TCP socket; "
1877 "pseudoterminal master in packet mode has seen state change in slave)."
1881 #: build/C/man2/poll.2:168
1887 #: build/C/man2/poll.2:174
1889 "Writing is now possible, though a write larger that the available space in a "
1890 "socket or pipe will still block (unless B<O_NONBLOCK> is set)."
1894 #: build/C/man2/poll.2:174
1896 msgid "B<POLLRDHUP> (since Linux 2.6.17)"
1900 #: build/C/man2/poll.2:185
1902 "Stream socket peer closed connection, or shut down writing half of "
1903 "connection. The B<_GNU_SOURCE> feature test macro must be defined (before "
1904 "including I<any> header files) in order to obtain this definition."
1908 #: build/C/man2/poll.2:185
1914 #: build/C/man2/poll.2:188
1915 msgid "Error condition (output only)."
1919 #: build/C/man2/poll.2:188
1925 #: build/C/man2/poll.2:191
1926 msgid "Hang up (output only)."
1930 #: build/C/man2/poll.2:191
1936 #: build/C/man2/poll.2:196
1937 msgid "Invalid request: I<fd> not open (output only)."
1941 #: build/C/man2/poll.2:202
1943 "When compiling with B<_XOPEN_SOURCE> defined, one also has the following, "
1944 "which convey no further information beyond the bits listed above:"
1948 #: build/C/man2/poll.2:203
1950 msgid "B<POLLRDNORM>"
1954 #: build/C/man2/poll.2:207
1955 msgid "Equivalent to B<POLLIN>."
1959 #: build/C/man2/poll.2:207
1961 msgid "B<POLLRDBAND>"
1964 #. POLLRDBAND is used in the DECnet protocol.
1966 #: build/C/man2/poll.2:211
1967 msgid "Priority band data can be read (generally unused on Linux)."
1971 #: build/C/man2/poll.2:211
1973 msgid "B<POLLWRNORM>"
1977 #: build/C/man2/poll.2:215
1978 msgid "Equivalent to B<POLLOUT>."
1982 #: build/C/man2/poll.2:215
1984 msgid "B<POLLWRBAND>"
1988 #: build/C/man2/poll.2:218
1989 msgid "Priority data may be written."
1993 #: build/C/man2/poll.2:222
1994 msgid "Linux also knows about, but does not use B<POLLMSG>."
1998 #: build/C/man2/poll.2:222
2004 #: build/C/man2/poll.2:236
2006 "The relationship between B<poll>() and B<ppoll>() is analogous to the "
2007 "relationship between B<select>(2) and B<pselect>(2): like B<pselect>(2), "
2008 "B<ppoll>() allows an application to safely wait until either a file "
2009 "descriptor becomes ready or until a signal is caught."
2013 #: build/C/man2/poll.2:242
2015 "Other than the difference in the precision of the I<timeout> argument, the "
2016 "following B<ppoll>() call:"
2020 #: build/C/man2/poll.2:245
2022 msgid " ready = ppoll(&fds, nfds, timeout_ts, &sigmask);\n"
2026 #: build/C/man2/poll.2:254
2029 " sigset_t origmask;\n"
2034 #: build/C/man2/poll.2:260
2037 " timeout = (timeout_ts == NULL) ? -1 :\n"
2038 " (timeout_ts.tv_sec * 1000 + timeout_ts.tv_nsec / 1000000);\n"
2039 " sigprocmask(SIG_SETMASK, &sigmask, &origmask);\n"
2040 " ready = poll(&fds, nfds, timeout);\n"
2041 " sigprocmask(SIG_SETMASK, &origmask, NULL);\n"
2045 #: build/C/man2/poll.2:267
2047 "See the description of B<pselect>(2) for an explanation of why B<ppoll>() "
2052 #: build/C/man2/poll.2:279
2054 "If the I<sigmask> argument is specified as NULL, then no signal mask "
2055 "manipulation is performed (and thus B<ppoll>() differs from B<poll>() only "
2056 "in the precision of the I<timeout> argument)."
2060 #: build/C/man2/poll.2:286
2062 "The I<timeout_ts> argument specifies an upper limit on the amount of time "
2063 "that B<ppoll>() will block. This argument is a pointer to a structure of "
2064 "the following form:"
2068 #: build/C/man2/poll.2:293
2071 "struct timespec {\n"
2072 " long tv_sec; /* seconds */\n"
2073 " long tv_nsec; /* nanoseconds */\n"
2078 #: build/C/man2/poll.2:301
2080 "If I<timeout_ts> is specified as NULL, then B<ppoll>() can block "
2085 #: build/C/man2/poll.2:311
2087 "On success, a positive number is returned; this is the number of structures "
2088 "which have nonzero I<revents> fields (in other words, those descriptors with "
2089 "events or errors reported). A value of 0 indicates that the call timed out "
2090 "and no file descriptors were ready. On error, -1 is returned, and I<errno> "
2091 "is set appropriately."
2095 #: build/C/man2/poll.2:316
2097 "The array given as argument was not contained in the calling program's "
2102 #: build/C/man2/poll.2:320
2103 msgid "A signal occurred before any requested event; see B<signal>(7)."
2107 #: build/C/man2/poll.2:327
2108 msgid "The I<nfds> value exceeds the B<RLIMIT_NOFILE> value."
2112 #: build/C/man2/poll.2:330
2113 msgid "There was no space to allocate file descriptor tables."
2116 #. library call was introduced in libc 5.4.28
2118 #: build/C/man2/poll.2:340
2120 "The B<poll>() system call was introduced in Linux 2.1.23. On older kernels "
2121 "that lack this system call, the glibc (and the old Linux libc) B<poll>() "
2122 "wrapper function provides emulation using B<select>(2)."
2126 #: build/C/man2/poll.2:347
2128 "The B<ppoll>() system call was added to Linux in kernel 2.6.16. The "
2129 "B<ppoll>() library call was added in glibc 2.4."
2132 #. NetBSD 3.0 has a pollts() which is like Linux ppoll().
2134 #: build/C/man2/poll.2:353
2135 msgid "B<poll>() conforms to POSIX.1-2001. B<ppoll>() is Linux-specific."
2139 #: build/C/man2/poll.2:361
2141 "Some implementations define the nonstandard constant B<INFTIM> with the "
2142 "value -1 for use as a I<timeout> for B<poll>(). This constant is not "
2143 "provided in glibc."
2147 #: build/C/man2/poll.2:366
2149 "For a discussion of what may happen if a file descriptor being monitored by "
2150 "B<poll>() is closed in another thread, see B<select>(2)."
2154 #: build/C/man2/poll.2:380
2156 "The Linux B<ppoll>() system call modifies its I<timeout_ts> argument. "
2157 "However, the glibc wrapper function hides this behavior by using a local "
2158 "variable for the timeout argument that is passed to the system call. Thus, "
2159 "the glibc B<ppoll>() function does not modify its I<timeout_ts> argument."
2163 #: build/C/man2/poll.2:393
2165 "The raw B<ppoll>() system call has a fifth argument, I<size_t sigsetsize>, "
2166 "which specifies the size in bytes of the I<sigmask> argument. The glibc "
2167 "B<ppoll>() wrapper function specifies this argument as a fixed value (equal "
2168 "to I<sizeof(sigset_t)>)."
2172 #: build/C/man2/poll.2:397
2174 "See the discussion of spurious readiness notifications under the BUGS "
2175 "section of B<select>(2)."
2179 #: build/C/man2/poll.2:402
2180 msgid "B<restart_syscall>(2), B<select>(2), B<select_tut>(2), B<time>(7)"