lib/libc/sys/eventfd.2

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