diff options
| -rw-r--r-- | usr/src/man/man3c/Makefile | 7 | ||||
| -rw-r--r-- | usr/src/man/man3c/eventfd.3c | 164 | ||||
| -rw-r--r-- | usr/src/pkg/manifests/system-library.man3c.inc | 4 |
3 files changed, 116 insertions, 59 deletions
diff --git a/usr/src/man/man3c/Makefile b/usr/src/man/man3c/Makefile index 0450a46eeb..1c76564c56 100644 --- a/usr/src/man/man3c/Makefile +++ b/usr/src/man/man3c/Makefile @@ -16,7 +16,7 @@ # Copyright 2014 Garrett D'Amore <garrett@damore.org> # Copyright 2020 Joyent, Inc. # Copyright 2018 Jason King -# Copyright 2019 OmniOS Community Edition (OmniOSce) Association. +# Copyright 2021 OmniOS Community Edition (OmniOSce) Association. # include $(SRC)/Makefile.master @@ -795,6 +795,8 @@ MANLINKS= FD_CLR.3c \ etext.3c \ euccol.3c \ eucscol.3c \ + eventfd_read.3c \ + eventfd_write.3c \ explicit_bzero.3c \ extended_to_decimal.3c \ fconvert.3c \ @@ -1755,6 +1757,9 @@ warnx.3c := LINKSRC = err.3c euccol.3c := LINKSRC = euclen.3c eucscol.3c := LINKSRC = euclen.3c +eventfd_read.3c := LINKSRC = eventfd.3c +eventfd_write.3c := LINKSRC = eventfd.3c + _exithandle.3c := LINKSRC = exit.3c clearerr.3c := LINKSRC = ferror.3c diff --git a/usr/src/man/man3c/eventfd.3c b/usr/src/man/man3c/eventfd.3c index a1b44439df..c7e21d22d7 100644 --- a/usr/src/man/man3c/eventfd.3c +++ b/usr/src/man/man3c/eventfd.3c @@ -10,12 +10,15 @@ .\" .\" .\" Copyright (c) 2014, Joyent, Inc. All Rights Reserved. +.\" Copyright 2021 OmniOS Community Edition (OmniOSce) Association. .\" -.Dd March 26, 2017 +.Dd August 10, 2021 .Dt EVENTFD 3C .Os .Sh NAME -.Nm eventfd +.Nm eventfd , +.Nm eventfd_read , +.Nm eventfd_write .Nd create a file descriptor for event notification .Sh SYNOPSIS .In sys/eventfd.h @@ -24,6 +27,16 @@ .Fa "unsigned int initval" .Fa "int flags" .Fc +.Ft int +.Fo eventfd_read +.Fa "int fd" +.Fa "eventfd_t *valp" +.Fc +.Ft int +.Fo eventfd_write +.Fa "int fd" +.Fa "eventfd_t val" +.Fc .Sh DESCRIPTION The .Fn eventfd @@ -33,10 +46,12 @@ instance that has an associated 64-bit unsigned counter. It returns a file descriptor that can be operated upon via .Xr read 2 , .Xr write 2 -and the facilities that notify of file descriptor activity (e.g., +and the facilities that notify of file descriptor activity +.Po e.g. , .Xr poll 2 , .Xr port_get 3C , -.Xr epoll_wait 3C Ns ). +.Xr epoll_wait 3C Ns +.Pc . To dispose of the instance, .Xr close 2 should be called on the file descriptor. @@ -45,36 +60,35 @@ The .Fa initval argument specifies the initial value of the 64-bit counter associated with the instance. -(Note that this limits the initial value to be a 32-bit quantity despite the -fact that the underlying counter is 64-bit.) +.Po +Note that this limits the initial value to be a 32-bit quantity despite the +fact that the underlying counter is 64-bit +.Pc . .Pp -The \fIflags\fR argument specifies additional parameters for the -instance, and can have any of the following values: -.Bl -hang -width Ds -.It Sy EFD_CLOEXEC -.Bd -filled -compact +The +.Fa flags +argument specifies additional parameters for the instance, and can have any of +the following values: +.Bl -tag -width Ds +.It Dv EFD_CLOEXEC Instance will be closed upon an .Xr exec 2 ; see .Xr open 2 Ns 's description of -.Sy O_CLOEXEC . -.Ed -.It Sy EFD_NONBLOCK -.Bd -filled -compact +.Dv O_CLOEXEC . +.It Dv EFD_NONBLOCK Instance will be set to be non-blocking. A .Xr read 2 on an -.Sy eventfd +.Nm eventfd instance that has been initialized with -.Sy EFD_NONBLOCK +.Dv EFD_NONBLOCK will return -.Sy EAGAIN +.Er EAGAIN in lieu of blocking if the count associated with the instance is zero. -.Ed -.It EFD_SEMAPHORE -.Bd -filled -compact +.It Dv EFD_SEMAPHORE Provide counting semaphore semantics whereby a .Xr read 2 will atomically decrement rather than atomically clear the count when it @@ -82,93 +96,127 @@ becomes non-zero. See below for details on .Xr read 2 semantics. -.Ed .El .Pp The following operations can be performed upon an -.Sy eventfd +.Nm eventfd instance: -.Bl -hang -width Ds -.It Sy read(2) -.Bd -filled -compact +.Bl -tag -width Ds +.It Xr read 2 Atomically reads and modifies the value of the 64-bit counter associated with the instance. The precise semantics of .Xr read 2 depend on the disposition of -.Sy EFD_SEMAPHORE +.Dv EFD_SEMAPHORE with respect to the instance: if -.Sy EFD_SEMAPHORE +.Dv EFD_SEMAPHORE was set when the instance was created, .Xr read 2 will .Em atomically decrement -the counter if (and when) it is non-zero, copying the value 1 to the eight -byte buffer passed to the system call; if -.Sy EFD_SEMAPHORE +the counter if +.Pq and when +it is non-zero, copying the value 1 to the eight byte buffer passed to the +system call; if +.Dv EFD_SEMAPHORE was not set, .Xr read 2 will .Em atomically clear -the counter if (and when) it is non-zero, copying the former value of the -counter to the eight byte buffer passed to the -system call. +the counter if +.Pq and when +it is non-zero, copying the former value of the counter to the eight byte +buffer passed to the system call. In either case, .Xr read 2 will block if the counter is -zero (or return -.Sy EAGAIN +zero +.Po or return +.Er EAGAIN if the instance was created with -.Sy EFD_NONBLOCK Ns ). +.Dv EFD_NONBLOCK +.Pc . If the buffer specified to .Xr read 2 is less than eight bytes in length, -.Sy EINVAL +.Er EINVAL will be returned. -.Ed -.It Sy write(2) -.Bd -filled -compact +.It Xr write 2 Atomically adds the 64-bit value pointed to by the buffer to the 64-bit counter associated with the instance. If the resulting value would overflow, the .Xr write 2 will block until the value would not overflow -(or return -.Sy EAGAIN -EAGAIN if the instance was created with -.Sy EFD_NONBLOCK Ns ). +.Po or return +.Er EAGAIN +if the instance was created with +.Dv EFD_NONBLOCK +.Pc . If the buffer specified to .Xr write 2 is less than eight bytes in length, -.Sy EINVAL +.Er EINVAL will be returned. -.Ed -.It Sy poll(2), port_get(3C), epoll_wait(3C) -.Bd -filled -compact +.It Xo +.Xr poll 2 , +.Xr port_get 3C , +.Xr epoll_wait 3C +.Xc Provide notification when the 64-bit counter associated with the instance is ready for reading or writing, as specified. If the 64-bit value associated with the instance is non-zero, -.Sy POLLIN +.Dv POLLIN and -.Sy POLLRDNORM +.Dv POLLRDNORM will be set; if the value 1 can be added the value without blocking, -.Sy POLLOUT +.Dv POLLOUT and -.Sy POLLWRNORM +.Dv POLLWRNORM will be set. -.Ed .El +.Pp +.Fn eventfd_read +and +.Fn eventfd_write +are provided for compatibility with +.Sy glibc +and are wrappers around +.Xr read 2 +and +.Xr write 2 , +respectively. +They return +.Sy 0 +if the correct number of bytes was transferred and +.Sy -1 +otherwise. +These functions may return +.Sy -1 +without setting +.Va errno . .Sh RETURN VALUES -Upon successful completion, a file descriptor associated with the instance -is returned. +Upon successful completion, +.Fn eventfd +returns a file descriptor associated with the instance. Otherwise, .Sy -1 is returned and -.Sy errno +.Va errno is set to indicate the error. +.Pp +Upon successful completion, +.Fn eventfd_read +and +.Fn eventfd_write +return +.Sy 0 . +Otherwise, +.Sy -1 +is returned. .Sh ERRORS The .Fn eventfd @@ -185,6 +233,8 @@ file descriptors open in the calling process. .El .Sh SEE ALSO .Xr poll 2 , +.Xr read 2 , +.Xr write 2 , .Xr epoll_wait 3C , .Xr port_get 3C , .Xr eventfd 5 diff --git a/usr/src/pkg/manifests/system-library.man3c.inc b/usr/src/pkg/manifests/system-library.man3c.inc index b45024541a..2b5f673f28 100644 --- a/usr/src/pkg/manifests/system-library.man3c.inc +++ b/usr/src/pkg/manifests/system-library.man3c.inc @@ -16,7 +16,7 @@ # Copyright 2014 Garrett D'Amore <garrett@damore.org> # Copyright 2018 Jason King # Copyright 2020 Joyent, Inc. -# Copyright 2019 OmniOS Community Edition (OmniOSce) Association. +# Copyright 2021 OmniOS Community Edition (OmniOSce) Association. # file path=usr/share/man/man3c/__fbufsize.3c @@ -796,6 +796,8 @@ link path=usr/share/man/man3c/errx.3c target=err.3c link path=usr/share/man/man3c/etext.3c target=end.3c link path=usr/share/man/man3c/euccol.3c target=euclen.3c link path=usr/share/man/man3c/eucscol.3c target=euclen.3c +link path=usr/share/man/man3c/eventfd_read.3c target=eventfd.3c +link path=usr/share/man/man3c/eventfd_write.3c target=eventfd.3c link path=usr/share/man/man3c/explicit_bzero.3c target=bstring.3c link path=usr/share/man/man3c/extended_to_decimal.3c \ target=floating_to_decimal.3c |