1.\" SPDX-License-Identifier: BSD-2-Clause 2.\" 3.\" Copyright (c) 2020 Greg V <[email protected]> 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" $FreeBSD$ 27.\" 28.Dd October 8, 2020 29.Dt EVENTFD 2 30.Os 31.Sh NAME 32.Nm eventfd 33.Nd create a file descriptor for event notification 34.Sh LIBRARY 35.Lb libc 36.Sh SYNOPSIS 37.In sys/eventfd.h 38.Ft int 39.Fn eventfd "unsigned int initval" "int flags" 40.Ft int 41.Fn eventfd_read "int fd" "eventfd_t *value" 42.Ft int 43.Fn eventfd_write "int fd" "eventfd_t value" 44.Sh DESCRIPTION 45.Fn eventfd 46creates a special file descriptor with event counter or semaphore semantics, 47designed for interprocess communication. 48The returned file descriptor refers to a kernel object containing an 49unsigned 64-bit integer counter, which is initialized with the value of the 50.Fa initval 51argument. 52.Pp 53The 54.Fa flags 55argument may contain the result of 56.Em or Ns 'ing 57the following values: 58.Pp 59.Bl -tag -width "EFD_SEMAPHORE" -compact 60.It Dv EFD_CLOEXEC 61set FD_CLOEXEC on the file descriptor 62.It Dv EFD_NONBLOCK 63do not block on read/write operations 64.It Dv EFD_SEMAPHORE 65use semaphore semantics 66.El 67.Pp 68File operations have the following semantics: 69.Bl -tag -width EFD_SEMAPHORE 70.It Xr read 2 71If the counter is zero, the call blocks until the counter becomes non-zero, unless 72.Dv EFD_NONBLOCK 73was set, in which case it would fail with 74.Dv EAGAIN 75instead. 76.Pp 77If the counter is non-zero: 78.Bl -bullet 79.It 80If 81.Dv EFD_SEMAPHORE 82is not set, the current value of the counter is returned, 83and the value is reset to zero. 84.It 85If 86.Dv EFD_SEMAPHORE 87is set, the constant 1 is returned, and the value is decremented by 1. 88.El 89.Pp 90The numeric value is encoded as 64-bit (8 bytes) in host byte order. 91The 92.Xr read 2 93call fails with 94.Dv EINVAL 95if there is less than 8 bytes available in the supplied buffer. 96.It Xr write 2 97Adds the given value to the counter. 98The maximum value that can be stored in the counter is the 99maximum unsigned 64-bit integer value minus one (0xfffffffffffffffe). 100.Pp 101If the resulting value exceeds the maximum, the call would block 102until the value is reduced by 103.Xr read 2 , 104unless 105.Dv EFD_NONBLOCK 106was set, in which case it would fail with 107.Dv EAGAIN 108instead. 109.Pp 110The numeric value is encoded as 64-bit (8 bytes) in host byte order. 111The 112.Xr write 2 113call fails with 114.Dv EINVAL 115if there is less than 8 bytes available in the supplied buffer, 116or if the value 0xffffffffffffffff is given. 117.It Xr poll 2 118When receiving notifications via 119.Xr poll 2 / 120.Xr ppoll 2 / 121.Xr select 2 / 122.Xr pselect 2 / 123.Xr kqueue 2 , 124the following semantics apply: 125.Bl -bullet 126.It 127The file descriptor is readable when the counter is greater than zero. 128.It 129The file descriptor is writable when the counter is less than the maximum value. 130.El 131.El 132.Pp 133File descriptors created by 134.Fn eventfd 135are passable to other processes via 136.Xr sendmsg 2 137and are preserved across 138.Xr fork 2 ; 139in both cases the descriptors refer to the same counter from both processes. 140Unless 141.Dv O_CLOEXEC 142flag was specified, 143the created file descriptor will remain open across 144.Xr execve 2 145system calls; see 146.Xr close 2 , 147.Xr fcntl 2 148and 149.Dv O_CLOEXEC 150description. 151.Pp 152.Fn eventfd_read 153and 154.Fn eventfd_write 155are thin wrappers around 156.Xr read 2 157and 158.Xr write 2 159system calls, 160provided for compatibility with glibc. 161.Sh RETURN VALUES 162If successful, 163.Fn eventfd 164returns a non-negative integer, termed a file descriptor. 165It returns \-1 on failure, and sets 166.Va errno 167to indicate the error. 168.Pp 169The 170.Fn eventfd_read 171and 172.Fn eventfd_write 173functions return 0 if the operation succeeded, -1 otherwise. 174.Sh ERRORS 175.Fn eventfd 176may fail with: 177.Bl -tag -width Er 178.It Bq Er EINVAL 179The 180.Fa flags 181argument given to 182.Fn eventfd 183has unknown bits set. 184.It Bq Er EMFILE 185The process has already reached its limit for open 186file descriptors. 187.It Bq Er ENFILE 188The system file table is full. 189.It Bq Er ENOMEM 190No memory was available to create the kernel object. 191.El 192.Sh SEE ALSO 193.Xr close 2 , 194.Xr kqueue 2 , 195.Xr poll 2 , 196.Xr read 2 , 197.Xr select 2 , 198.Xr write 2 199.Sh STANDARDS 200The 201.Fn eventfd 202system call is non-standard. 203It is present in Linux. 204.Sh HISTORY 205The 206.Fn eventfd 207system call first appeared in 208.Fx 13.0 . 209