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 Dec 3, 2014 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. It returns a file 33descriptor 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. (Note that this limits the initial value to be a 32-bit quantity 48despite the fact that the underlying counter is 64-bit.) 49.Pp 50The \fIflags\fR argument specifies additional parameters for the 51instance, and can have any of the following values: 52.Bl -hang -width Ds 53.It Sy EFD_CLOEXEC 54.Bd -filled -compact 55Instance will be closed upon an 56.Xr exec 2 ; 57see 58.Xr open 2 Ns 's 59description of 60.Sy O_CLOEXEC . 61.Ed 62.It Sy EFD_NONBLOCK 63.Bd -filled -compact 64Instance will be set to be non-blocking. A 65.Xr read 2 66on an 67.Sy eventfd 68instance that has been initialized with 69.Sy EFD_NONBLOCK 70will return 71.Sy EAGAIN 72in lieu of blocking if the count associated with the instance is zero. 73.Ed 74.It EFD_SEMAPHORE 75.Bd -filled -compact 76Provide counting semaphore semantics whereby a 77.Xr read 2 78will atomically decrement rather than atomically clear the count when it 79becomes non-zero. See below for details on 80.Xr read 2 81semantics. 82.Ed 83.El 84.Pp 85The following operations can be performed upon an 86.Sy eventfd 87instance: 88.Bl -hang -width Ds 89.It Sy read(2) 90.Bd -filled -compact 91Atomically reads and modifies the value of the 64-bit counter associated 92with the instance. The precise semantics 93of 94.Xr read 2 95depend on the disposition of 96.Sy EFD_SEMAPHORE 97with 98respect to the instance: if 99.Sy EFD_SEMAPTHORE 100was set when the instance was created, 101.Xr read 2 102will 103.Em atomically decrement 104the counter if (and when) it is non-zero, copying the value 1 to the eight 105byte buffer passed to the system call; if 106.Sy EFD_SEMAPHORE 107was not set, 108.Xr read 2 109will 110.Em atomically clear 111the counter if (and when) it is non-zero, copying the former value of the 112counter to the eight byte buffer passed to the 113system call. In either case, 114.Xr read 2 115will block if the counter is 116zero (or return 117.Sy EAGAIN 118if the instance was created with 119.Sy EFD_NONBLOCK Ns ). 120If the buffer specified to 121.Xr read 2 122is less than 123eight bytes in length, 124.Sy EINVAL 125will be returned. 126.Ed 127.It Sy write(2) 128.Bd -filled -compact 129Atomically adds the 64-bit value pointed to by the buffer to the 64-bit 130counter associated with the instance. If the resulting value would overflow, 131the 132.Xr write 2 133will block until the value would not overflow 134(or return 135.Sy EAGAIN 136EAGAIN if the instance was created with 137.Sy EFD_NONBLOCK Ns ). 138If the buffer specified to 139.Xr write 2 140is less than eight bytes in length, 141.Sy EINVAL 142will be returned. 143.Ed 144.It Sy poll(2), port_get(3C), epoll_wait(3C) 145.Bd -filled -compact 146Provide notification when the 64-bit counter associated 147with the instance is ready for reading or writing, as specified. 148If the 64-bit value associated with the instance is non-zero, 149.Sy POLLIN 150and 151.Sy POLLRDNORM 152will be set; if the value 1 can be added the value 153without blocking, 154.Sy POLLOUT 155and 156.Sy POLLWRNORM 157will be set. 158.Ed 159.El 160.Sh RETURN VALUES 161Upon succesful completion, a file descriptor associated with the instance 162is returned. Otherwise, 163.Sy -1 is returned and 164.Sy errno 165is set to indicate the error. 166.Sh ERRORS 167The 168.Fn eventfd 169function will fail if: 170.Bl -tag -width Er 171.It Er EINVAL 172The 173.Fa flags 174are invalid. 175.It Er EMFILE 176There are currently 177.Pf { Sy OPEN_MAX Ns } 178file descriptors open in the calling process. 179.El 180.Sh SEE ALSO 181.Xr poll 2 , 182.Xr port_get 3C , 183.Xr epoll_wait 3C , 184.Xr eventfd 5 185