1.\" SPDX-License-Identifier: BSD-2-Clause 2.\" 3.\" Copyright (c) 2020 Val Packett <val@packett.cool> 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.Dd October 8, 2020 27.Dt EVENTFD 2 28.Os 29.Sh NAME 30.Nm eventfd 31.Nd create a file descriptor for event notification 32.Sh LIBRARY 33.Lb libc 34.Sh SYNOPSIS 35.In sys/eventfd.h 36.Ft int 37.Fn eventfd "unsigned int initval" "int flags" 38.Ft int 39.Fn eventfd_read "int fd" "eventfd_t *value" 40.Ft int 41.Fn eventfd_write "int fd" "eventfd_t value" 42.Sh DESCRIPTION 43.Fn eventfd 44creates a special file descriptor with event counter or semaphore semantics, 45designed for interprocess communication. 46The returned file descriptor refers to a kernel object containing an 47unsigned 64-bit integer counter, which is initialized with the value of the 48.Fa initval 49argument. 50.Pp 51The 52.Fa flags 53argument may contain the result of 54.Em or Ns 'ing 55the following values: 56.Pp 57.Bl -tag -width "EFD_SEMAPHORE" -compact 58.It Dv EFD_CLOEXEC 59set FD_CLOEXEC on the file descriptor 60.It Dv EFD_NONBLOCK 61do not block on read/write operations 62.It Dv EFD_SEMAPHORE 63use semaphore semantics 64.El 65.Pp 66File operations have the following semantics: 67.Bl -tag -width EFD_SEMAPHORE 68.It Xr read 2 69If the counter is zero, the call blocks until the counter becomes non-zero, unless 70.Dv EFD_NONBLOCK 71was set, in which case it would fail with 72.Dv EAGAIN 73instead. 74.Pp 75If the counter is non-zero: 76.Bl -bullet 77.It 78If 79.Dv EFD_SEMAPHORE 80is not set, the current value of the counter is returned, 81and the value is reset to zero. 82.It 83If 84.Dv EFD_SEMAPHORE 85is set, the constant 1 is returned, and the value is decremented by 1. 86.El 87.Pp 88The numeric value is encoded as 64-bit (8 bytes) in host byte order. 89The 90.Xr read 2 91call fails with 92.Dv EINVAL 93if there is less than 8 bytes available in the supplied buffer. 94.It Xr write 2 95Adds the given value to the counter. 96The maximum value that can be stored in the counter is the 97maximum unsigned 64-bit integer value minus one (0xfffffffffffffffe). 98.Pp 99If the resulting value exceeds the maximum, the call would block 100until the value is reduced by 101.Xr read 2 , 102unless 103.Dv EFD_NONBLOCK 104was set, in which case it would fail with 105.Dv EAGAIN 106instead. 107.Pp 108The numeric value is encoded as 64-bit (8 bytes) in host byte order. 109The 110.Xr write 2 111call fails with 112.Dv EINVAL 113if there is less than 8 bytes available in the supplied buffer, 114or if the value 0xffffffffffffffff is given. 115.It Xr poll 2 116When receiving notifications via 117.Xr poll 2 / 118.Xr ppoll 2 / 119.Xr select 2 / 120.Xr pselect 2 / 121.Xr kqueue 2 , 122the following semantics apply: 123.Bl -bullet 124.It 125The file descriptor is readable when the counter is greater than zero. 126.It 127The file descriptor is writable when the counter is less than the maximum value. 128.El 129.El 130.Pp 131File descriptors created by 132.Fn eventfd 133are passable to other processes via 134.Xr sendmsg 2 135and are preserved across 136.Xr fork 2 ; 137in both cases the descriptors refer to the same counter from both processes. 138Unless 139.Dv O_CLOEXEC 140flag was specified, 141the created file descriptor will remain open across 142.Xr execve 2 143system calls; see 144.Xr close 2 , 145.Xr fcntl 2 146and 147.Dv O_CLOEXEC 148description. 149.Pp 150.Fn eventfd_read 151and 152.Fn eventfd_write 153are thin wrappers around 154.Xr read 2 155and 156.Xr write 2 157system calls, 158provided for compatibility with glibc. 159.Sh RETURN VALUES 160If successful, 161.Fn eventfd 162returns a non-negative integer, termed a file descriptor. 163It returns \-1 on failure, and sets 164.Va errno 165to indicate the error. 166.Pp 167The 168.Fn eventfd_read 169and 170.Fn eventfd_write 171functions return 0 if the operation succeeded, -1 otherwise. 172.Sh ERRORS 173.Fn eventfd 174may fail with: 175.Bl -tag -width Er 176.It Bq Er EINVAL 177The 178.Fa flags 179argument given to 180.Fn eventfd 181has unknown bits set. 182.It Bq Er EMFILE 183The process has already reached its limit for open 184file descriptors. 185.It Bq Er ENFILE 186The system file table is full. 187.It Bq Er ENOMEM 188No memory was available to create the kernel object. 189.El 190.Sh SEE ALSO 191.Xr close 2 , 192.Xr kqueue 2 , 193.Xr poll 2 , 194.Xr read 2 , 195.Xr select 2 , 196.Xr write 2 197.Sh STANDARDS 198The 199.Fn eventfd 200system call is non-standard. 201It is present in Linux. 202.Sh HISTORY 203The 204.Fn eventfd 205system call first appeared in 206.Fx 13.0 . 207