lib/libc/sys/eventfd.2

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