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