diff options
author | Michael Kerrisk <mtk.manpages@gmail.com> | 2016-03-10 20:45:47 +0100 |
---|---|---|
committer | Michael Kerrisk <mtk.manpages@gmail.com> | 2016-03-15 06:48:20 +1300 |
commit | 6a6d83b2c736faea028ebbc3aec97ac6d326afef (patch) | |
tree | c6a92fdccb9be1124c2a5efedcfc50a72d9bb0f9 | |
parent | 1754f8d0f7c3c7caace603e33a3d96088d9932ae (diff) | |
download | man-pages-6a6d83b2c736faea028ebbc3aec97ac6d326afef.tar.gz |
epoll_ctl.2: Document EPOLLEXCLUSIVE
Cowritten-by: Jason Baron <jbaron@akamai.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
-rw-r--r-- | man2/epoll_ctl.2 | 98 |
1 files changed, 98 insertions, 0 deletions
diff --git a/man2/epoll_ctl.2 b/man2/epoll_ctl.2 index 476b36770b..7acc42ef35 100644 --- a/man2/epoll_ctl.2 +++ b/man2/epoll_ctl.2 @@ -186,6 +186,71 @@ or the clearing of for the event file descriptor with .BR EPOLL_CTL_MOD . See also BUGS. +.TP +.BR EPOLLEXCLUSIVE " (since Linux 4.5)" +Sets an exclusive wakeup mode for the epoll file descriptor that is being +attached to the target file descriptor, +.IR fd . +When a wakeup event occurs and multiple epoll file descriptors +are attached to the same target file using +.BR EPOLLEXCLUSIVE , +one or more of the epoll file descriptors will receive an event with +.BR epoll_wait (2). +The default in this scenario (when +.BR EPOLLEXCLUSIVE +is not set) is for all epoll file descriptors to receive an event. +.BR EPOLLEXCLUSIVE +is thus useful for avoiding thundering herd problems in certain scenarios. + +If the same file descriptor is in multiple epoll instances, +some with the +.BR EPOLLEXCLUSIVE +flag, and others without, then events will provided to all epoll +instances that did not specify +.BR EPOLLEXCLUSIVE , +and at least one of the epoll instances that did specify +.BR EPOLLEXCLUSIVE . + +The following values may be specified in conjunction with +.BR EPOLLEXCLUSIVE : +.BR EPOLLIN , +.BR EPOLLOUT , +.BR EPOLLWAKEUP, +and +.BR EPOLLET . +.BR EPOLLHUP +and +.BR EPOLLERR +can also be specified, but are ignored (as usual). +Attempts to specify other values in +.I events +yield an error. +.B EPOLLEXCLUSIVE +may be used only in an +.B EPOLL_CTL_ADD +operation; attempts to employ it with +.B EPOLL_CTL_MOD +yield an error. +If +.B EPOLLEXCLUSIVE +has set using +.BR epoll_ctl (2), +then a subsequent +.B EPOLL_CTL_MOD +on the same +.IR epfd ",\ " fd +pair yields an error. +A call to +.BR epoll_ctl (2) +that specifies +.B EPOLLEXCLUSIVE +in +.I events +and specifies the target file descriptor +.I fd +as an epoll instance will likewise fail. +The error in all of these cases is +.BR EINVAL . .SH RETURN VALUE When successful, .BR epoll_ctl () @@ -231,6 +296,39 @@ refers to an epoll instance and this operation would result in a circular loop of epoll instances monitoring one another. .TP +.B EINVAL +An invalid event type was specified along with +.B EPOLLEXCLUSIVE +in +.IR events . +.TP +.B EINVAL +.I op +was +.B EPOLL_CTL_MOD +and +.IR events +included +.BR EPOLLEXCLUSIVE . +.TP +.B EINVAL +.I op +was +.B EPOLL_CTL_MOD +and the +.BR EPOLLEXCLUSIVE +flag has previously been applied to this +.IR epfd ",\ " fd +pair. +.TP +.B EINVAL +.BR EPOLLEXCLUSIVE +was specified in +.IR event +and +.I fd +refers to an epoll instance. +.TP .B ENOENT .I op was |