1 '\" te
2 .\" Copyright (c) 2014, Joyent, Inc. All Rights Reserved.
3 .\" This file and its contents are supplied under the terms of the
4 .\" Common Development and Distribution License ("CDDL"), version 1.0.
5 .\" You may only use this file in accordance with the terms of version
6 .\" 1.0 of the CDDL.
7 .\"
8 .\" A full copy of the text of the CDDL should have accompanied this
9 .\" source. A copy of the CDDL is also available via the Internet at
10 .\" http://www.illumos.org/license/CDDL.
11 .TH EPOLL 5 "Apr 17, 2014"
12 .SH NAME
13 epoll \- Linux-compatible I/O event notification facility
14 .SH SYNOPSIS
15 .nf
16 #include <sys/epoll.h>
17 .fi
18
19 .SH DESCRIPTION
20 \fBepoll\fR is a facility for efficient event-oriented I/O that has a
21 similar model to \fBpoll\fR(2), but does not necessitate rescanning a
22 set of file descriptors to wait for an event. \fBepoll\fR is of Linux
23 origins, and this facility is designed to be binary-compatible with
24 the Linux facility, including the following interfaces:
25
26 .RS +4
27 .TP
28 .ie t \(bu
29 .el o
30 \fBepoll_create\fR(3C) creates an \fBepoll\fR instance, returning a file
31 descriptor. It contains a size arugment which is meaningful only in as
32 much as it cannot be 0.
33 .RE
34 .RS +4
35 .TP
36 .ie t \(bu
37 .el o
38 \fBepoll_create1\fR(3C) also creates an \fBepoll\fR instance, but eliminates
39 the meaningless size argument -- replacing it instead with a flags
40 argument.
41 .RE
42 .RS +4
43 .TP
44 .ie t \(bu
45 .el o
46 \fBepoll_ctl\fR(3C) allows file descriptors to be added
47 (via \fBEPOLL_CTL_ADD\fR), deleted (via \fBEPOLL_CTL_DEL\fR) or
48 modified (via \fBEPOLL_CTL_MOD\fR) with respect to the \fBepoll\fR'd set
49 of file descriptors.
50 .RE
51 .RS +4
52 .TP
53 .ie t \(bu
54 .el o
55 \fBepoll_wait\fR(3C) fetches pending events for file descriptors added
56 via \fBepoll_ctl\fR(3C), blocking the caller if no such events are pending.
57 .RE
58 .RS +4
59 .TP
60 .ie t \(bu
61 .el o
62 \fBepoll_pwait\fR(3C) opeates in a similar manner to \fBepoll_wait\fR(3C), but
63 allows the caller to specify a signal mask to be set atomically with respect
64 to waiting for events.
65 .RE
66
67 .sp
68 .SH NOTES
69 The \fBepoll\fR facility is implemented
70 for purposes of offering compatibility to and portability of Linux-borne
71 applications; native applications should continue to prefer using event ports
72 via the \fBport_create\fR(3C),
73 \fBport_associate\fR(3C) and \fBport_getn\fR(3C) interfaces.
74 In particular, use of \fBepoll\fR in a multithreaded environment is fraught
75 with peril; even when using \fBEPOLLONESHOT\fR for one-shot events,
76 there are race conditions with respect to \fBclose\fR(2) that are unresolvable.
77 (For more details, see the aborted effort in Linux to resolve this via the
78 proposed
79 \fBEPOLL_CTL_DISABLE\fR operation.)
80 The event port facility -- like the BSD kqueue facility that inspired it --
81 is designed to deal with such issues via explicit event source dissociation.
82
|
1 '\" te
2 .\" Copyright (c) 2014, Joyent, Inc. All Rights Reserved.
3 .\" This file and its contents are supplied under the terms of the
4 .\" Common Development and Distribution License ("CDDL"), version 1.0.
5 .\" You may only use this file in accordance with the terms of version
6 .\" 1.0 of the CDDL.
7 .\"
8 .\" A full copy of the text of the CDDL should have accompanied this
9 .\" source. A copy of the CDDL is also available via the Internet at
10 .\" http://www.illumos.org/license/CDDL.
11 .TH EPOLL 5 "May 16, 2020"
12 .SH NAME
13 epoll \- Linux-compatible I/O event notification facility
14 .SH SYNOPSIS
15 .nf
16 #include <sys/epoll.h>
17 .fi
18
19 .SH DESCRIPTION
20 \fBepoll\fR is a facility for efficient event-oriented I/O that has a
21 similar model to \fBpoll\fR(2), but does not necessitate rescanning a
22 set of file descriptors to wait for an event. \fBepoll\fR is of Linux
23 origins, and this facility is designed to be binary-compatible with
24 the Linux facility, including the following interfaces:
25
26 .RS +4
27 .TP
28 .ie t \(bu
29 .el o
30 \fBepoll_create\fR(3C) creates an \fBepoll\fR instance, returning a file
31 descriptor. It contains a size argument which is meaningful only in as
32 much as it cannot be 0.
33 .RE
34 .RS +4
35 .TP
36 .ie t \(bu
37 .el o
38 \fBepoll_create1\fR(3C) also creates an \fBepoll\fR instance, but eliminates
39 the meaningless size argument -- replacing it instead with a flags
40 argument.
41 .RE
42 .RS +4
43 .TP
44 .ie t \(bu
45 .el o
46 \fBepoll_ctl\fR(3C) allows file descriptors to be added
47 (via \fBEPOLL_CTL_ADD\fR), deleted (via \fBEPOLL_CTL_DEL\fR) or
48 modified (via \fBEPOLL_CTL_MOD\fR) with respect to the \fBepoll\fR'd set
49 of file descriptors.
50 .RE
51 .RS +4
52 .TP
53 .ie t \(bu
54 .el o
55 \fBepoll_wait\fR(3C) fetches pending events for file descriptors added
56 via \fBepoll_ctl\fR(3C), blocking the caller if no such events are pending.
57 .RE
58 .RS +4
59 .TP
60 .ie t \(bu
61 .el o
62 \fBepoll_pwait\fR(3C) operates in a similar manner to \fBepoll_wait\fR(3C), but
63 allows the caller to specify a signal mask to be set atomically with respect
64 to waiting for events.
65 .RE
66
67 .sp
68 .SH NOTES
69 The \fBepoll\fR facility is implemented
70 for purposes of offering compatibility to and portability of Linux-borne
71 applications; native applications should continue to prefer using event ports
72 via the \fBport_create\fR(3C),
73 \fBport_associate\fR(3C) and \fBport_getn\fR(3C) interfaces.
74 In particular, use of \fBepoll\fR in a multithreaded environment is fraught
75 with peril; even when using \fBEPOLLONESHOT\fR for one-shot events,
76 there are race conditions with respect to \fBclose\fR(2) that are unresolvable.
77 (For more details, see the aborted effort in Linux to resolve this via the
78 proposed
79 \fBEPOLL_CTL_DISABLE\fR operation.)
80 The event port facility -- like the BSD kqueue facility that inspired it --
81 is designed to deal with such issues via explicit event source dissociation.
82
|