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.\" Copyright 2021 OmniOS Community Edition (OmniOSce) Association. 14.\" 15.Dd August 10, 2021 16.Dt EVENTFD 3C 17.Os 18.Sh NAME 19.Nm eventfd , 20.Nm eventfd_read , 21.Nm eventfd_write 22.Nd create a file descriptor for event notification 23.Sh SYNOPSIS 24.In sys/eventfd.h 25.Ft int 26.Fo eventfd 27.Fa "unsigned int initval" 28.Fa "int flags" 29.Fc 30.Ft int 31.Fo eventfd_read 32.Fa "int fd" 33.Fa "eventfd_t *valp" 34.Fc 35.Ft int 36.Fo eventfd_write 37.Fa "int fd" 38.Fa "eventfd_t val" 39.Fc 40.Sh DESCRIPTION 41The 42.Fn eventfd 43function creates an 44.Xr eventfd 7 45instance that has an associated 64-bit unsigned counter. 46It returns a file descriptor that can be operated upon via 47.Xr read 2 , 48.Xr write 2 49and the facilities that notify of file descriptor activity 50.Po e.g. , 51.Xr poll 2 , 52.Xr port_get 3C , 53.Xr epoll_wait 3C Ns 54.Pc . 55To dispose of the instance, 56.Xr close 2 57should be called on the file descriptor. 58.Pp 59The 60.Fa initval 61argument specifies the initial value of the 64-bit counter associated with the 62instance. 63.Po 64Note that this limits the initial value to be a 32-bit quantity despite the 65fact that the underlying counter is 64-bit 66.Pc . 67.Pp 68The 69.Fa flags 70argument specifies additional parameters for the instance, and can have any of 71the following values: 72.Bl -tag -width Ds 73.It Dv EFD_CLOEXEC 74Instance will be closed upon an 75.Xr exec 2 ; 76see 77.Xr open 2 Ns 's 78description of 79.Dv O_CLOEXEC . 80.It Dv EFD_NONBLOCK 81Instance will be set to be non-blocking. 82A 83.Xr read 2 84on an 85.Nm eventfd 86instance that has been initialized with 87.Dv EFD_NONBLOCK 88will return 89.Er EAGAIN 90in lieu of blocking if the count associated with the instance is zero. 91.It Dv EFD_SEMAPHORE 92Provide counting semaphore semantics whereby a 93.Xr read 2 94will atomically decrement rather than atomically clear the count when it 95becomes non-zero. 96See below for details on 97.Xr read 2 98semantics. 99.El 100.Pp 101The following operations can be performed upon an 102.Nm eventfd 103instance: 104.Bl -tag -width Ds 105.It Xr read 2 106Atomically reads and modifies the value of the 64-bit counter associated 107with the instance. 108The precise semantics of 109.Xr read 2 110depend on the disposition of 111.Dv EFD_SEMAPHORE 112with 113respect to the instance: if 114.Dv EFD_SEMAPHORE 115was set when the instance was created, 116.Xr read 2 117will 118.Em atomically decrement 119the counter if 120.Pq and when 121it is non-zero, copying the value 1 to the eight byte buffer passed to the 122system call; if 123.Dv EFD_SEMAPHORE 124was not set, 125.Xr read 2 126will 127.Em atomically clear 128the counter if 129.Pq and when 130it is non-zero, copying the former value of the counter to the eight byte 131buffer passed to the system call. 132In either case, 133.Xr read 2 134will block if the counter is 135zero 136.Po or return 137.Er EAGAIN 138if the instance was created with 139.Dv EFD_NONBLOCK 140.Pc . 141If the buffer specified to 142.Xr read 2 143is less than 144eight bytes in length, 145.Er EINVAL 146will be returned. 147.It Xr write 2 148Atomically adds the 64-bit value pointed to by the buffer to the 64-bit 149counter associated with the instance. 150If the resulting value would overflow, the 151.Xr write 2 152will block until the value would not overflow 153.Po or return 154.Er EAGAIN 155if the instance was created with 156.Dv EFD_NONBLOCK 157.Pc . 158If the buffer specified to 159.Xr write 2 160is less than eight bytes in length, 161.Er EINVAL 162will be returned. 163.It Xo 164.Xr poll 2 , 165.Xr port_get 3C , 166.Xr epoll_wait 3C 167.Xc 168Provide notification when the 64-bit counter associated 169with the instance is ready for reading or writing, as specified. 170If the 64-bit value associated with the instance is non-zero, 171.Dv POLLIN 172and 173.Dv POLLRDNORM 174will be set; if the value 1 can be added the value 175without blocking, 176.Dv POLLOUT 177and 178.Dv POLLWRNORM 179will be set. 180.El 181.Pp 182.Fn eventfd_read 183and 184.Fn eventfd_write 185are provided for compatibility with 186.Sy glibc 187and are wrappers around 188.Xr read 2 189and 190.Xr write 2 , 191respectively. 192They return 193.Sy 0 194if the correct number of bytes was transferred and 195.Sy -1 196otherwise. 197These functions may return 198.Sy -1 199without setting 200.Va errno . 201.Sh RETURN VALUES 202Upon successful completion, 203.Fn eventfd 204returns a file descriptor associated with the instance. 205Otherwise, 206.Sy -1 207is returned and 208.Va errno 209is set to indicate the error. 210.Pp 211Upon successful completion, 212.Fn eventfd_read 213and 214.Fn eventfd_write 215return 216.Sy 0 . 217Otherwise, 218.Sy -1 219is returned. 220.Sh ERRORS 221The 222.Fn eventfd 223function will fail if: 224.Bl -tag -width Er 225.It Er EINVAL 226The 227.Fa flags 228are invalid. 229.It Er EMFILE 230There are currently 231.Pf { Sy OPEN_MAX Ns } 232file descriptors open in the calling process. 233.El 234.Sh SEE ALSO 235.Xr poll 2 , 236.Xr read 2 , 237.Xr write 2 , 238.Xr epoll_wait 3C , 239.Xr port_get 3C , 240.Xr eventfd 7 241