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 Dec 3, 2014
  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. It returns a file
  33 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.  (Note that this limits the initial value to be a 32-bit quantity
  48 despite the fact that the underlying counter is 64-bit.)
  49 .Pp
  50 The \fIflags\fR argument specifies additional parameters for the
  51 instance, and can have any of the following values:
  52 .Bl -hang -width Ds
  53 .It Sy EFD_CLOEXEC
  54 .Bd -filled -compact
  55 Instance will be closed upon an
  56 .Xr exec 2 ;
  57 see
  58 .Xr open 2 Ns 's
  59 description of
  60 .Sy O_CLOEXEC .
  61 .Ed
  62 .It Sy EFD_NONBLOCK
  63 .Bd -filled -compact
  64 Instance will be set to be non-blocking.  A
  65 .Xr read 2
  66 on an
  67 .Sy eventfd
  68 instance that has been initialized with
  69 .Sy EFD_NONBLOCK
  70 will return
  71 .Sy EAGAIN
  72 in lieu of blocking if the count associated with the instance is zero.
  73 .Ed
  74 .It EFD_SEMAPHORE
  75 .Bd -filled -compact
  76 Provide counting semaphore semantics whereby a
  77 .Xr read 2
  78 will atomically decrement rather than atomically clear the count when it
  79 becomes non-zero. See below for details on
  80 .Xr read 2
  81 semantics.
  82 .Ed
  83 .El
  84 .Pp
  85 The following operations can be performed upon an
  86 .Sy eventfd
  87 instance:
  88 .Bl -hang -width Ds
  89 .It Sy read(2)
  90 .Bd -filled -compact
  91 Atomically reads and modifies the value of the 64-bit counter associated
  92 with the instance.  The precise semantics
  93 of
  94 .Xr read 2
  95 depend on the disposition of
  96 .Sy EFD_SEMAPHORE
  97 with
  98 respect to the instance: if
  99 .Sy EFD_SEMAPTHORE
 100 was set when the instance was created,
 101 .Xr read 2
 102 will
 103 .Em atomically decrement
 104 the counter if (and when) it is non-zero, copying the value 1 to the eight
 105 byte buffer passed to the system call; if
 106 .Sy EFD_SEMAPHORE
 107 was not set,
 108 .Xr read 2
 109 will
 110 .Em atomically clear
 111 the counter if (and when) it is non-zero, copying the former value of the
 112 counter to the eight byte buffer passed to the
 113 system call.  In either case,
 114 .Xr read 2
 115 will block if the counter is
 116 zero (or return
 117 .Sy EAGAIN
 118 if the instance was created with
 119 .Sy EFD_NONBLOCK Ns ).
 120 If the buffer specified to
 121 .Xr read 2
 122 is less than
 123 eight bytes in length,
 124 .Sy EINVAL
 125 will be returned.
 126 .Ed
 127 .It Sy write(2)
 128 .Bd -filled -compact
 129 Atomically adds the 64-bit value pointed to by the buffer to the 64-bit
 130 counter associated with the instance.  If the resulting value would overflow,
 131 the
 132 .Xr write 2
 133 will block until the value would not overflow
 134 (or return
 135 .Sy EAGAIN
 136 EAGAIN if the instance was created with
 137 .Sy EFD_NONBLOCK Ns ).
 138 If the buffer specified to
 139 .Xr write 2
 140 is less than eight bytes in length,
 141 .Sy EINVAL
 142 will be returned.
 143 .Ed
 144 .It Sy poll(2), port_get(3C), epoll_wait(3C)
 145 .Bd -filled -compact
 146 Provide notification when the 64-bit counter associated
 147 with the instance is ready for reading or writing, as specified.
 148 If the 64-bit value associated with the instance is non-zero,
 149 .Sy POLLIN
 150 and
 151 .Sy POLLRDNORM
 152 will be set; if the value 1 can be added the value
 153 without blocking,
 154 .Sy POLLOUT
 155 and
 156 .Sy POLLWRNORM
 157 will be set.
 158 .Ed
 159 .El
 160 .Sh RETURN VALUES
 161 Upon succesful completion, a file descriptor associated with the instance
 162 is returned. Otherwise,
 163 .Sy -1 is returned and
 164 .Sy errno
 165 is set to indicate the error.
 166 .Sh ERRORS
 167 The
 168 .Fn eventfd
 169 function will fail if:
 170 .Bl -tag -width Er
 171 .It Er EINVAL
 172 The
 173 .Fa flags
 174 are invalid.
 175 .It Er EMFILE
 176 There are currently
 177 .Pf { Sy OPEN_MAX Ns }
 178 file descriptors open in the calling process.
 179 .El
 180 .Sh SEE ALSO
 181 .Xr poll 2 ,
 182 .Xr port_get 3C ,
 183 .Xr epoll_wait 3C ,
 184 .Xr eventfd 5