1.\" $NetBSD: eventfd.2,v 1.2 2021/09/23 13:16:13 uwe Exp $ 2.\" 3.\" Copyright (c) 2021 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Jason R. Thorpe. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd September 17, 2021 31.Dt EVENTFD 2 32.Os 33.\" 34.\" 35.Sh NAME 36.Nm eventfd , 37.Nm eventfd_read , 38.Nm eventfd_write 39.Nd create and interact with a counting event descriptor 40.\" 41.\" 42.Sh SYNOPSIS 43.In sys/eventfd.h 44.Ft int 45.Fn eventfd "unsigned int val" "int flags" 46.Ft int 47.Fn eventfd_read "int efd" "eventfd_t *valp" 48.Ft int 49.Fn eventfd_write "int efd" "eventfd_t val" 50.\" 51.\" 52.Sh DESCRIPTION 53The 54.Nm 55interface presents a simple counting object associated with a file descriptor. 56Writes and reads to this file descriptor increment and decrement the count, 57respectively. 58When the object's value is non-zero, the file descriptor is considered 59.Dq readable , 60and when the count is less than the maximum value 61.Li UINT64_MAX\^-\^1 62it is considered 63.Dq writable . 64When an 65.Nm 66object is no longer needed, it may be disposed of using 67.Xr close 2 . 68.Pp 69All I/O to an 70.Nm 71object is 8\~bytes in length, which is the space required to store an 72unsigned 64-bit integer. 73Any read or write with a buffer smaller than 8\~bytes will fail with 74.Er EINVAL . 75Only the first 8\~bytes of the buffer will be used. 76.Pp 77The 78.Fn eventfd 79function creates a new counting event object and returns a file descriptor 80representing that object. 81The initial value of the object is specified by the 82.Fa val 83argument. 84The following flags define the behavior of the resulting object: 85.Bl -tag -width Dv 86.It Dv EFD_CLOEXEC 87This is an alias for the 88.Dv O_CLOEXEC 89flag; see 90.Xr open 2 91for more information. 92.It Dv EFD_NONBLOCK 93This is an alias for the 94.Dv O_NONBLOCK 95flag; see 96.Xr open 2 97for more information. 98.It Dv EFD_SEMAPHORE 99Creates a 100.Dq semaphore mode 101object; see below for details. 102.El 103.Pp 104Reads from an 105.Nm 106object return an unsigned 64-bit integer in the caller's buffer. 107The semantics of this value are dependent on whether the 108.Nm 109object was created in 110.Dq semaphore mode : 111.Bl -bullet 112.It 113If the 114.Nm 115object was created in 116.Dq semaphore mode , 117reads return the value\~1 118and object's counter is decremented by\~1. 119.It 120If the 121.Nm 122object was not created in 123.Dq semaphore mode , 124reads return the current value of the object's counter 125and reset the counter to\~0. 126.El 127.Pp 128If the value of the 129.Nm 130object's counter is\~0, 131then reads will block, unless the 132.Nm 133object is set for non-blocking I/O. 134.Pp 135Writing to an 136.Nm 137object adds the unsigned 64-bit value provided in the caller's buffer 138to the 139.Nm 140object's counter. 141If adding the specified value would exceed the maximum value, then the 142write will block, unless the 143.Nm 144object is set for non-blocking I/O. 145.Pp 146The convenience functions 147.Fn eventfd_read 148and 149.Fn eventfd_write 150are provided to simplify interacting with 151.Nm 152objects, and are simply wrappers around the 153.Xr read 2 154and 155.Xr write 2 156system calls: 157.Bl -tag -width Fn 158.It Fn eventfd_read efd valp 159Reads the unsigned 64-bit integer value of the 160.Nm 161object and returns it in 162.Fa valp . 163.It Fn eventfd_write efd val 164Writes the unsigned 64-bit integer value 165.Fa val 166to the 167.Nm 168object. 169.El 170.\" 171.\" 172.Sh RETURN VALUES 173The 174.Fn eventfd 175system call returns\~\-1 if an error occurs, 176otherwise the return value is a descriptor representing the 177.Nm 178object. 179.Pp 180.Rv -std eventfd_read eventfd_write 181.\" 182.\" 183.Sh ERRORS 184The 185.Fn eventfd 186system call fails if: 187.Bl -tag -width Er 188.It Bq Er EINVAL 189Flags other than 190.Dv EFD_CLOEXEC , 191.Dv EFD_NONBLOCK , 192and 193.Dv EFD_SEMAPHORE 194are set in the 195.Fa flags 196argument. 197.It Bq Er EMFILE 198The per-process descriptor table is full. 199.It Bq Er ENFILE 200The system file table is full. 201.El 202.Pp 203The 204.Fn eventfd_read 205function fails if: 206.Bl -tag -width Er 207.It Bq Er EAGAIN 208The value of the 209.Nm 210object is\~0 and the 211.Nm 212object is set for non-blocking I/O. 213.El 214.Pp 215The 216.Fn eventfd_write 217function fails if: 218.Bl -tag -width Er 219.It Bq Er EAGAIN 220The resulting value of the 221.Nm 222object after adding the value 223.Fa val 224would exceed the maximum value 225.Li UINT64_MAX\^-\^1 226and the 227.Nm 228object is set for non-blocking I/O. 229.It Bq Er EINVAL 230An attempt was made to write a value greater than the maximum value. 231.El 232.Pp 233In addition to the errors returned by 234.Fn eventfd_read 235and 236.Fn eventfd_write , 237a read from or write to an 238.Nm 239object fails if: 240.Bl -tag -width Er 241.It Bq Er EINVAL 242The size of the buffer is less than 8\~bytes 243.Pq the size required to hold an unsigned 64-bit integer . 244.El 245.\" 246.\" 247.Sh SEE ALSO 248.Xr close 2 , 249.Xr kevent 2 , 250.Xr open 2 , 251.Xr poll 2 , 252.Xr read 2 , 253.Xr select 2 , 254.Xr write 2 255.\" 256.\" 257.Sh HISTORY 258The 259.Nm 260interface first appeared in 261.Nx 10 . 262It is compatible with the 263.Nm 264interface that appeared in Linux 2.6.30. 265