1.\" 2.\" This file and its contents are supplied under the terms of the 3.\" Common Development and Distribution License ("CDDL"), version 1.0. 4.\" You may only use this file in accordance with the terms of version 5.\" 1.0 of the CDDL. 6.\" 7.\" A full copy of the text of the CDDL should have accompanied this 8.\" source. A copy of the CDDL is also available via the Internet at 9.\" http://www.illumos.org/license/CDDL. 10.\" 11.\" 12.\" Copyright (c) 2014, Joyent, Inc. All Rights Reserved. 13.\" 14.Dd March 26, 2017 15.Dt EVENTFD 3C 16.Os 17.Sh NAME 18.Nm eventfd 19.Nd create a file descriptor for event notification 20.Sh SYNOPSIS 21.In sys/eventfd.h 22.Ft int 23.Fo eventfd 24.Fa "unsigned int initval" 25.Fa "int flags" 26.Fc 27.Sh DESCRIPTION 28The 29.Fn eventfd 30function creates an 31.Xr eventfd 5 32instance that has an associated 64-bit unsigned counter. 33It returns a file descriptor that can be operated upon via 34.Xr read 2 , 35.Xr write 2 36and the facilities that notify of file descriptor activity (e.g., 37.Xr poll 2 , 38.Xr port_get 3C , 39.Xr epoll_wait 3C Ns ). 40To dispose of the instance, 41.Xr close 2 42should be called on the file descriptor. 43.Pp 44The 45.Fa initval 46argument specifies the initial value of the 64-bit counter associated with the 47instance. 48(Note that this limits the initial value to be a 32-bit quantity despite the 49fact that the underlying counter is 64-bit.) 50.Pp 51The \fIflags\fR argument specifies additional parameters for the 52instance, and can have any of the following values: 53.Bl -hang -width Ds 54.It Sy EFD_CLOEXEC 55.Bd -filled -compact 56Instance will be closed upon an 57.Xr exec 2 ; 58see 59.Xr open 2 Ns 's 60description of 61.Sy O_CLOEXEC . 62.Ed 63.It Sy EFD_NONBLOCK 64.Bd -filled -compact 65Instance will be set to be non-blocking. 66A 67.Xr read 2 68on an 69.Sy eventfd 70instance that has been initialized with 71.Sy EFD_NONBLOCK 72will return 73.Sy EAGAIN 74in lieu of blocking if the count associated with the instance is zero. 75.Ed 76.It EFD_SEMAPHORE 77.Bd -filled -compact 78Provide counting semaphore semantics whereby a 79.Xr read 2 80will atomically decrement rather than atomically clear the count when it 81becomes non-zero. 82See below for details on 83.Xr read 2 84semantics. 85.Ed 86.El 87.Pp 88The following operations can be performed upon an 89.Sy eventfd 90instance: 91.Bl -hang -width Ds 92.It Sy read(2) 93.Bd -filled -compact 94Atomically reads and modifies the value of the 64-bit counter associated 95with the instance. 96The precise semantics of 97.Xr read 2 98depend on the disposition of 99.Sy EFD_SEMAPHORE 100with 101respect to the instance: if 102.Sy EFD_SEMAPHORE 103was set when the instance was created, 104.Xr read 2 105will 106.Em atomically decrement 107the counter if (and when) it is non-zero, copying the value 1 to the eight 108byte buffer passed to the system call; if 109.Sy EFD_SEMAPHORE 110was not set, 111.Xr read 2 112will 113.Em atomically clear 114the counter if (and when) it is non-zero, copying the former value of the 115counter to the eight byte buffer passed to the 116system call. 117In either case, 118.Xr read 2 119will block if the counter is 120zero (or return 121.Sy EAGAIN 122if the instance was created with 123.Sy EFD_NONBLOCK Ns ). 124If the buffer specified to 125.Xr read 2 126is less than 127eight bytes in length, 128.Sy EINVAL 129will be returned. 130.Ed 131.It Sy write(2) 132.Bd -filled -compact 133Atomically adds the 64-bit value pointed to by the buffer to the 64-bit 134counter associated with the instance. 135If the resulting value would overflow, the 136.Xr write 2 137will block until the value would not overflow 138(or return 139.Sy EAGAIN 140EAGAIN if the instance was created with 141.Sy EFD_NONBLOCK Ns ). 142If the buffer specified to 143.Xr write 2 144is less than eight bytes in length, 145.Sy EINVAL 146will be returned. 147.Ed 148.It Sy poll(2), port_get(3C), epoll_wait(3C) 149.Bd -filled -compact 150Provide notification when the 64-bit counter associated 151with the instance is ready for reading or writing, as specified. 152If the 64-bit value associated with the instance is non-zero, 153.Sy POLLIN 154and 155.Sy POLLRDNORM 156will be set; if the value 1 can be added the value 157without blocking, 158.Sy POLLOUT 159and 160.Sy POLLWRNORM 161will be set. 162.Ed 163.El 164.Sh RETURN VALUES 165Upon successful completion, a file descriptor associated with the instance 166is returned. 167Otherwise, 168.Sy -1 169is returned and 170.Sy errno 171is set to indicate the error. 172.Sh ERRORS 173The 174.Fn eventfd 175function will fail if: 176.Bl -tag -width Er 177.It Er EINVAL 178The 179.Fa flags 180are invalid. 181.It Er EMFILE 182There are currently 183.Pf { Sy OPEN_MAX Ns } 184file descriptors open in the calling process. 185.El 186.Sh SEE ALSO 187.Xr poll 2 , 188.Xr epoll_wait 3C , 189.Xr port_get 3C , 190.Xr eventfd 5 191