Print this page
11622 clean up rarer mandoc lint warnings
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man5/epoll.5
+++ new/usr/src/man/man5/epoll.5
1 1 '\" te
2 2 .\" Copyright (c) 2014, Joyent, Inc. All Rights Reserved.
3 3 .\" This file and its contents are supplied under the terms of the
4 4 .\" Common Development and Distribution License ("CDDL"), version 1.0.
5 5 .\" You may only use this file in accordance with the terms of version
6 6 .\" 1.0 of the CDDL.
7 -.\"
7 +.\"
8 8 .\" A full copy of the text of the CDDL should have accompanied this
9 9 .\" source. A copy of the CDDL is also available via the Internet at
10 10 .\" http://www.illumos.org/license/CDDL.
11 11 .TH EPOLL 5 "Apr 17, 2014"
12 12 .SH NAME
13 13 epoll \- Linux-compatible I/O event notification facility
14 14 .SH SYNOPSIS
15 -
16 -.LP
17 15 .nf
18 16 #include <sys/epoll.h>
19 17 .fi
20 18
21 19 .SH DESCRIPTION
22 -.LP
23 -
24 20 \fBepoll\fR is a facility for efficient event-oriented I/O that has a
25 21 similar model to \fBpoll\fR(2), but does not necessitate rescanning a
26 22 set of file descriptors to wait for an event. \fBepoll\fR is of Linux
27 23 origins, and this facility is designed to be binary-compatible with
28 24 the Linux facility, including the following interfaces:
29 25
30 26 .RS +4
31 27 .TP
32 28 .ie t \(bu
33 29 .el o
34 30 \fBepoll_create\fR(3C) creates an \fBepoll\fR instance, returning a file
35 31 descriptor. It contains a size arugment which is meaningful only in as
36 32 much as it cannot be 0.
37 33 .RE
38 34 .RS +4
39 35 .TP
40 36 .ie t \(bu
41 37 .el o
42 38 \fBepoll_create1\fR(3C) also creates an \fBepoll\fR instance, but eliminates
43 39 the meaningless size argument -- replacing it instead with a flags
44 40 argument.
45 41 .RE
46 42 .RS +4
47 43 .TP
48 44 .ie t \(bu
49 45 .el o
50 46 \fBepoll_ctl\fR(3C) allows file descriptors to be added
51 47 (via \fBEPOLL_CTL_ADD\fR), deleted (via \fBEPOLL_CTL_DEL\fR) or
52 48 modified (via \fBEPOLL_CTL_MOD\fR) with respect to the \fBepoll\fR'd set
53 49 of file descriptors.
54 50 .RE
55 51 .RS +4
56 52 .TP
57 53 .ie t \(bu
58 54 .el o
59 55 \fBepoll_wait\fR(3C) fetches pending events for file descriptors added
60 56 via \fBepoll_ctl\fR(3C), blocking the caller if no such events are pending.
61 57 .RE
62 58 .RS +4
|
↓ open down ↓ |
29 lines elided |
↑ open up ↑ |
63 59 .TP
64 60 .ie t \(bu
65 61 .el o
66 62 \fBepoll_pwait\fR(3C) opeates in a similar manner to \fBepoll_wait\fR(3C), but
67 63 allows the caller to specify a signal mask to be set atomically with respect
68 64 to waiting for events.
69 65 .RE
70 66
71 67 .sp
72 68 .SH NOTES
73 -.LP
74 -
75 69 The \fBepoll\fR facility is implemented
76 70 for purposes of offering compatibility to and portability of Linux-borne
77 71 applications; native applications should continue to prefer using event ports
78 72 via the \fBport_create\fR(3C),
79 73 \fBport_associate\fR(3C) and \fBport_getn\fR(3C) interfaces.
80 74 In particular, use of \fBepoll\fR in a multithreaded environment is fraught
81 75 with peril; even when using \fBEPOLLONESHOT\fR for one-shot events,
82 76 there are race conditions with respect to \fBclose\fR(2) that are unresolvable.
83 77 (For more details, see the aborted effort in Linux to resolve this via the
84 78 proposed
85 79 \fBEPOLL_CTL_DISABLE\fR operation.)
86 80 The event port facility -- like the BSD kqueue facility that inspired it --
87 81 is designed to deal with such issues via explicit event source dissociation.
88 82
89 83 While a best effort has been made to mimic the Linux semantics, there
90 84 are some semantics that are too peculiar or ill-conceived to merit
91 85 accommodation. In particular, the Linux \fBepoll\fR facility will -- by
92 86 design -- continue to generate events for closed file descriptors where/when
93 87 the underlying file description remains open. For example, if one were
94 88 to \fBfork\fR(2) and subsequently close an actively \fBepoll\fR'd file
|
↓ open down ↓ |
10 lines elided |
↑ open up ↑ |
95 89 descriptor in the parent,
96 90 any events generated in the child on the implicitly duplicated file descriptor
97 91 will continue to be delivered to the parent -- despite the fact that the
98 92 parent itself no longer has any notion of the file description!
99 93 This \fBepoll\fR facility refuses to honor
100 94 these semantics; closing the \fBEPOLL_CTL_ADD\fR'd file descriptor
101 95 will always result in no further
102 96 events being generated for that event description.
103 97
104 98 .SH SEE ALSO
105 -.LP
106 99 \fBepoll_create\fR(3C), \fBepoll_create1\fR(3C), \fBepoll_ctl\fR(3C),
107 100 \fBepoll_wait\fR(3C), \fBepoll_pwait\fR(3C),
108 101 \fBport_create\fR(3C), \fBport_associate\fR(3C), \fBport_dissociate\fR(3C),
109 102 \fBport_get\fR(3C),
110 103 \fBpselect\fR(3C)
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX