xref: /titanic_50/usr/src/man/man3c/eventfd.3c (revision 3a005aada8ac0e291c13cbc488ba9ae1473f0a96)
11767006bSBryan Cantrill.\"
21767006bSBryan Cantrill.\" This file and its contents are supplied under the terms of the
31767006bSBryan Cantrill.\" Common Development and Distribution License ("CDDL"), version 1.0.
41767006bSBryan Cantrill.\" You may only use this file in accordance with the terms of version
51767006bSBryan Cantrill.\" 1.0 of the CDDL.
61767006bSBryan Cantrill.\"
71767006bSBryan Cantrill.\" A full copy of the text of the CDDL should have accompanied this
81767006bSBryan Cantrill.\" source.  A copy of the CDDL is also available via the Internet at
91767006bSBryan Cantrill.\" http://www.illumos.org/license/CDDL.
101767006bSBryan Cantrill.\"
111767006bSBryan Cantrill.\"
121767006bSBryan Cantrill.\" Copyright (c) 2014, Joyent, Inc. All Rights Reserved.
131767006bSBryan Cantrill.\"
141767006bSBryan Cantrill.Dd Dec 3, 2014
151767006bSBryan Cantrill.Dt EVENTFD 3C
161767006bSBryan Cantrill.Os
171767006bSBryan Cantrill.Sh NAME
181767006bSBryan Cantrill.Nm eventfd
191767006bSBryan Cantrill.Nd create a file descriptor for event notification
201767006bSBryan Cantrill.Sh SYNOPSIS
211767006bSBryan Cantrill.In sys/eventfd.h
221767006bSBryan Cantrill.Ft int
231767006bSBryan Cantrill.Fo eventfd
241767006bSBryan Cantrill.Fa "unsigned int initval"
251767006bSBryan Cantrill.Fa "int flags"
261767006bSBryan Cantrill.Fc
271767006bSBryan Cantrill.Sh DESCRIPTION
281767006bSBryan CantrillThe
291767006bSBryan Cantrill.Fn eventfd
301767006bSBryan Cantrillfunction creates an
311767006bSBryan Cantrill.Xr eventfd 5
321767006bSBryan Cantrillinstance that has an associated 64-bit unsigned counter. It returns a file
331767006bSBryan Cantrilldescriptor that can be operated upon via
341767006bSBryan Cantrill.Xr read 2 ,
351767006bSBryan Cantrill.Xr write 2
361767006bSBryan Cantrilland the facilities that notify of file descriptor activity (e.g.,
371767006bSBryan Cantrill.Xr poll 2 ,
381767006bSBryan Cantrill.Xr port_get 3C ,
391767006bSBryan Cantrill.Xr epoll_wait 3C Ns ).
401767006bSBryan CantrillTo dispose of the instance,
411767006bSBryan Cantrill.Xr close 2
421767006bSBryan Cantrillshould be called on the file descriptor.
431767006bSBryan Cantrill.Pp
441767006bSBryan CantrillThe
451767006bSBryan Cantrill.Fa initval
461767006bSBryan Cantrillargument specifies the initial value of the 64-bit counter associated with the
471767006bSBryan Cantrillinstance.  (Note that this limits the initial value to be a 32-bit quantity
481767006bSBryan Cantrilldespite the fact that the underlying counter is 64-bit.)
491767006bSBryan Cantrill.Pp
501767006bSBryan CantrillThe \fIflags\fR argument specifies additional parameters for the
511767006bSBryan Cantrillinstance, and can have any of the following values:
521767006bSBryan Cantrill.Bl -hang -width Ds
531767006bSBryan Cantrill.It Sy EFD_CLOEXEC
541767006bSBryan Cantrill.Bd -filled -compact
551767006bSBryan CantrillInstance will be closed upon an
561767006bSBryan Cantrill.Xr exec 2 ;
571767006bSBryan Cantrillsee
581767006bSBryan Cantrill.Xr open 2 Ns 's
591767006bSBryan Cantrilldescription of
601767006bSBryan Cantrill.Sy O_CLOEXEC .
611767006bSBryan Cantrill.Ed
621767006bSBryan Cantrill.It Sy EFD_NONBLOCK
631767006bSBryan Cantrill.Bd -filled -compact
641767006bSBryan CantrillInstance will be set to be non-blocking.  A
651767006bSBryan Cantrill.Xr read 2
661767006bSBryan Cantrillon an
671767006bSBryan Cantrill.Sy eventfd
681767006bSBryan Cantrillinstance that has been initialized with
691767006bSBryan Cantrill.Sy EFD_NONBLOCK
701767006bSBryan Cantrillwill return
711767006bSBryan Cantrill.Sy EAGAIN
721767006bSBryan Cantrillin lieu of blocking if the count associated with the instance is zero.
731767006bSBryan Cantrill.Ed
741767006bSBryan Cantrill.It EFD_SEMAPHORE
751767006bSBryan Cantrill.Bd -filled -compact
761767006bSBryan CantrillProvide counting semaphore semantics whereby a
771767006bSBryan Cantrill.Xr read 2
781767006bSBryan Cantrillwill atomically decrement rather than atomically clear the count when it
791767006bSBryan Cantrillbecomes non-zero. See below for details on
801767006bSBryan Cantrill.Xr read 2
811767006bSBryan Cantrillsemantics.
821767006bSBryan Cantrill.Ed
831767006bSBryan Cantrill.El
841767006bSBryan Cantrill.Pp
851767006bSBryan CantrillThe following operations can be performed upon an
861767006bSBryan Cantrill.Sy eventfd
871767006bSBryan Cantrillinstance:
881767006bSBryan Cantrill.Bl -hang -width Ds
891767006bSBryan Cantrill.It Sy read(2)
901767006bSBryan Cantrill.Bd -filled -compact
911767006bSBryan CantrillAtomically reads and modifies the value of the 64-bit counter associated
921767006bSBryan Cantrillwith the instance.  The precise semantics
931767006bSBryan Cantrillof
941767006bSBryan Cantrill.Xr read 2
951767006bSBryan Cantrilldepend on the disposition of
961767006bSBryan Cantrill.Sy EFD_SEMAPHORE
971767006bSBryan Cantrillwith
981767006bSBryan Cantrillrespect to the instance: if
991767006bSBryan Cantrill.Sy EFD_SEMAPTHORE
1001767006bSBryan Cantrillwas set when the instance was created,
1011767006bSBryan Cantrill.Xr read 2
1021767006bSBryan Cantrillwill
1031767006bSBryan Cantrill.Em atomically decrement
1041767006bSBryan Cantrillthe counter if (and when) it is non-zero, copying the value 1 to the eight
1051767006bSBryan Cantrillbyte buffer passed to the system call; if
1061767006bSBryan Cantrill.Sy EFD_SEMAPHORE
1071767006bSBryan Cantrillwas not set,
1081767006bSBryan Cantrill.Xr read 2
1091767006bSBryan Cantrillwill
1101767006bSBryan Cantrill.Em atomically clear
1111767006bSBryan Cantrillthe counter if (and when) it is non-zero, copying the former value of the
1121767006bSBryan Cantrillcounter to the eight byte buffer passed to the
1131767006bSBryan Cantrillsystem call.  In either case,
1141767006bSBryan Cantrill.Xr read 2
1151767006bSBryan Cantrillwill block if the counter is
1161767006bSBryan Cantrillzero (or return
1171767006bSBryan Cantrill.Sy EAGAIN
1181767006bSBryan Cantrillif the instance was created with
1191767006bSBryan Cantrill.Sy EFD_NONBLOCK Ns ).
1201767006bSBryan CantrillIf the buffer specified to
1211767006bSBryan Cantrill.Xr read 2
1221767006bSBryan Cantrillis less than
1231767006bSBryan Cantrilleight bytes in length,
1241767006bSBryan Cantrill.Sy EINVAL
1251767006bSBryan Cantrillwill be returned.
1261767006bSBryan Cantrill.Ed
1271767006bSBryan Cantrill.It Sy write(2)
1281767006bSBryan Cantrill.Bd -filled -compact
1291767006bSBryan CantrillAtomically adds the 64-bit value pointed to by the buffer to the 64-bit
1301767006bSBryan Cantrillcounter associated with the instance.  If the resulting value would overflow,
1311767006bSBryan Cantrillthe
1321767006bSBryan Cantrill.Xr write 2
1331767006bSBryan Cantrillwill block until the value would not overflow
1341767006bSBryan Cantrill(or return
1351767006bSBryan Cantrill.Sy EAGAIN
1361767006bSBryan CantrillEAGAIN if the instance was created with
1371767006bSBryan Cantrill.Sy EFD_NONBLOCK Ns ).
1381767006bSBryan CantrillIf the buffer specified to
1391767006bSBryan Cantrill.Xr write 2
1401767006bSBryan Cantrillis less than eight bytes in length,
1411767006bSBryan Cantrill.Sy EINVAL
1421767006bSBryan Cantrillwill be returned.
1431767006bSBryan Cantrill.Ed
1441767006bSBryan Cantrill.It Sy poll(2), port_get(3C), epoll_wait(3C)
1451767006bSBryan Cantrill.Bd -filled -compact
1461767006bSBryan CantrillProvide notification when the 64-bit counter associated
1471767006bSBryan Cantrillwith the instance is ready for reading or writing, as specified.
1481767006bSBryan CantrillIf the 64-bit value associated with the instance is non-zero,
1491767006bSBryan Cantrill.Sy POLLIN
1501767006bSBryan Cantrilland
1511767006bSBryan Cantrill.Sy POLLRDNORM
1521767006bSBryan Cantrillwill be set; if the value 1 can be added the value
1531767006bSBryan Cantrillwithout blocking,
1541767006bSBryan Cantrill.Sy POLLOUT
1551767006bSBryan Cantrilland
1561767006bSBryan Cantrill.Sy POLLWRNORM
1571767006bSBryan Cantrillwill be set.
1581767006bSBryan Cantrill.Ed
1591767006bSBryan Cantrill.El
1601767006bSBryan Cantrill.Sh RETURN VALUES
1611767006bSBryan CantrillUpon succesful completion, a file descriptor associated with the instance
1621767006bSBryan Cantrillis returned. Otherwise,
1631767006bSBryan Cantrill.Sy -1 is returned and
1641767006bSBryan Cantrill.Sy errno
1651767006bSBryan Cantrillis set to indicate the error.
1661767006bSBryan Cantrill.Sh ERRORS
1671767006bSBryan CantrillThe
1681767006bSBryan Cantrill.Fn eventfd
1691767006bSBryan Cantrillfunction will fail if:
1701767006bSBryan Cantrill.Bl -tag -width Er
1711767006bSBryan Cantrill.It Er EINVAL
1721767006bSBryan CantrillThe
1731767006bSBryan Cantrill.Fa flags
1741767006bSBryan Cantrillare invalid.
1751767006bSBryan Cantrill.It Er EMFILE
1761767006bSBryan CantrillThere are currently
1771767006bSBryan Cantrill.Pf { Sy OPEN_MAX Ns }
1781767006bSBryan Cantrillfile descriptors open in the calling process.
1791767006bSBryan Cantrill.El
1801767006bSBryan Cantrill.Sh SEE ALSO
1811767006bSBryan Cantrill.Xr poll 2 ,
1821767006bSBryan Cantrill.Xr epoll_wait 3C ,
183*3a005aadSYuri Pankov.Xr port_get 3C ,
1841767006bSBryan Cantrill.Xr eventfd 5
185