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