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