usr/src/man/man3c/eventfd.3c

   1 .\"
   2 .\" This file and its contents are supplied under the terms of the
   3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4 .\" You may only use this file in accordance with the terms of version
   5 .\" 1.0 of the CDDL.
   6 .\"
   7 .\" A full copy of the text of the CDDL should have accompanied this
   8 .\" source.  A copy of the CDDL is also available via the Internet at
   9 .\" http://www.illumos.org/license/CDDL.
  10 .\"
  11 .\"
  12 .\" Copyright (c) 2014, Joyent, Inc. All Rights Reserved.
  13 .\"
  14 .Dd March 26, 2017
  15 .Dt EVENTFD 3C
  16 .Os
  17 .Sh NAME
  18 .Nm eventfd
  19 .Nd create a file descriptor for event notification
  20 .Sh SYNOPSIS
  21 .In sys/eventfd.h
  22 .Ft int
  23 .Fo eventfd
  24 .Fa "unsigned int initval"
  25 .Fa "int flags"
  26 .Fc
  27 .Sh DESCRIPTION
  28 The
  29 .Fn eventfd
  30 function creates an
  31 .Xr eventfd 5
  32 instance that has an associated 64-bit unsigned counter.
  33 It returns a file descriptor that can be operated upon via
  34 .Xr read 2 ,
  35 .Xr write 2
  36 and the facilities that notify of file descriptor activity (e.g.,
  37 .Xr poll 2 ,
  38 .Xr port_get 3C ,
  39 .Xr epoll_wait 3C Ns ).
  40 To dispose of the instance,
  41 .Xr close 2
  42 should be called on the file descriptor.
  43 .Pp
  44 The
  45 .Fa initval
  46 argument specifies the initial value of the 64-bit counter associated with the
  47 instance.
  48 (Note that this limits the initial value to be a 32-bit quantity despite the
  49 fact that the underlying counter is 64-bit.)
  50 .Pp
  51 The \fIflags\fR argument specifies additional parameters for the
  52 instance, and can have any of the following values:
  53 .Bl -hang -width Ds
  54 .It Sy EFD_CLOEXEC
  55 .Bd -filled -compact
  56 Instance will be closed upon an
  57 .Xr exec 2 ;
  58 see
  59 .Xr open 2 Ns 's
  60 description of
  61 .Sy O_CLOEXEC .
  62 .Ed
  63 .It Sy EFD_NONBLOCK
  64 .Bd -filled -compact
  65 Instance will be set to be non-blocking.
  66 A
  67 .Xr read 2
  68 on an
  69 .Sy eventfd
  70 instance that has been initialized with
  71 .Sy EFD_NONBLOCK
  72 will return
  73 .Sy EAGAIN
  74 in lieu of blocking if the count associated with the instance is zero.
  75 .Ed
  76 .It EFD_SEMAPHORE
  77 .Bd -filled -compact
  78 Provide counting semaphore semantics whereby a
  79 .Xr read 2
  80 will atomically decrement rather than atomically clear the count when it
  81 becomes non-zero.
  82 See below for details on
  83 .Xr read 2
  84 semantics.
  85 .Ed
  86 .El
  87 .Pp
  88 The following operations can be performed upon an
  89 .Sy eventfd
  90 instance:
  91 .Bl -hang -width Ds
  92 .It Sy read(2)
  93 .Bd -filled -compact
  94 Atomically reads and modifies the value of the 64-bit counter associated
  95 with the instance.
  96 The precise semantics of
  97 .Xr read 2
  98 depend on the disposition of
  99 .Sy EFD_SEMAPHORE
 100 with
 101 respect to the instance: if
 102 .Sy EFD_SEMAPHORE
 103 was set when the instance was created,
 104 .Xr read 2
 105 will
 106 .Em atomically decrement
 107 the counter if (and when) it is non-zero, copying the value 1 to the eight
 108 byte buffer passed to the system call; if
 109 .Sy EFD_SEMAPHORE
 110 was not set,
 111 .Xr read 2
 112 will
 113 .Em atomically clear
 114 the counter if (and when) it is non-zero, copying the former value of the
 115 counter to the eight byte buffer passed to the
 116 system call.
 117 In either case,
 118 .Xr read 2
 119 will block if the counter is
 120 zero (or return
 121 .Sy EAGAIN
 122 if the instance was created with
 123 .Sy EFD_NONBLOCK Ns ).
 124 If the buffer specified to
 125 .Xr read 2
 126 is less than
 127 eight bytes in length,
 128 .Sy EINVAL
 129 will be returned.
 130 .Ed
 131 .It Sy write(2)
 132 .Bd -filled -compact
 133 Atomically adds the 64-bit value pointed to by the buffer to the 64-bit
 134 counter associated with the instance.
 135 If the resulting value would overflow, the
 136 .Xr write 2
 137 will block until the value would not overflow
 138 (or return
 139 .Sy EAGAIN
 140 EAGAIN if the instance was created with
 141 .Sy EFD_NONBLOCK Ns ).
 142 If the buffer specified to
 143 .Xr write 2
 144 is less than eight bytes in length,
 145 .Sy EINVAL
 146 will be returned.
 147 .Ed
 148 .It Sy poll(2), port_get(3C), epoll_wait(3C)
 149 .Bd -filled -compact
 150 Provide notification when the 64-bit counter associated
 151 with the instance is ready for reading or writing, as specified.
 152 If the 64-bit value associated with the instance is non-zero,
 153 .Sy POLLIN
 154 and
 155 .Sy POLLRDNORM
 156 will be set; if the value 1 can be added the value
 157 without blocking,
 158 .Sy POLLOUT
 159 and
 160 .Sy POLLWRNORM
 161 will be set.
 162 .Ed
 163 .El
 164 .Sh RETURN VALUES
 165 Upon successful completion, a file descriptor associated with the instance
 166 is returned.
 167 Otherwise,
 168 .Sy -1
 169 is returned and
 170 .Sy errno
 171 is set to indicate the error.
 172 .Sh ERRORS
 173 The
 174 .Fn eventfd
 175 function will fail if:
 176 .Bl -tag -width Er
 177 .It Er EINVAL
 178 The
 179 .Fa flags
 180 are invalid.
 181 .It Er EMFILE
 182 There are currently
 183 .Pf { Sy OPEN_MAX Ns }
 184 file descriptors open in the calling process.
 185 .El
 186 .Sh SEE ALSO
 187 .Xr poll 2 ,
 188 .Xr epoll_wait 3C ,
 189 .Xr port_get 3C ,
 190 .Xr eventfd 5