[illumos-gate merge]

commit 1767006bb066ef500b90b432fba79d63d0d09b36
    6188 add support for eventfd

Conflicts:
	usr/src/cmd/devfsadm/misc_link.c
	usr/src/lib/libc/i386/Makefile.com
	usr/src/lib/libc/sparc/Makefile.com
	usr/src/lib/libc/sparcv9/Makefile.com
	usr/src/man/man3c/eventfd.3c
	usr/src/man/man5/eventfd.5
	usr/src/uts/common/Makefile.files
	usr/src/uts/common/io/eventfd.c
	usr/src/uts/sparc/Makefile.sparc

1 files changed, 173 insertions, 150 deletions

diff --git a/usr/src/man/man3c/eventfd.3c b/usr/src/man/man3c/eventfd.3c
index 6e7d1c6a5b..3a9f8be284 100644
--- a/usr/src/man/man3c/eventfd.3c
+++ b/usr/src/man/man3c/eventfd.3c
@@ -1,161 +1,184 @@
-'\" te
-.\"  Copyright (c) 2014, Joyent, Inc. All Rights Reserved.
-.\"  This file and its contents are supplied under the terms of the
-.\"  Common Development and Distribution License ("CDDL"), version 1.0.
-.\"  You may only use this file in accordance with the terms of version
-.\"  1.0 of the CDDL.
-.\" 
-.\"  A full copy of the text of the CDDL should have accompanied this
-.\"  source.  A copy of the CDDL is also available via the Internet at
-.\"  http://www.illumos.org/license/CDDL.
-.TH EVENTFD 3C "Dec 3, 2014"
-.SH NAME
-eventfd \- create a file descriptor for event notification
-.SH SYNOPSIS
-
-.LP
-.nf
-#include <sys/eventfd.h>
-
-\fBint\fR \fBeventfd\fR(\fBunsigned int\fR \fIinitval\fR, \fBint\fR \fIflags\fR);
-.fi
-
-.SH DESCRIPTION
-.sp
-.LP
-The \fBeventfd()\fR function creates an \fBeventfd\fR(5) instance that
-has an associated 64-bit unsigned counter. It returns a file descriptor
-that can be operated upon via \fBread\fR(2), \fBwrite\fR(2) and the facilities
-that notify of file descriptor activity (e.g., \fBpoll\fR(2),
-\fBport_get\fR(3C), \fBepoll_wait\fR(3C)). To dispose of the instance,
-\fBclose\fR(2) should be called on the file descriptor.
-
-The \fIinitval\fR 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.)
-
+.\"
+.\" This file and its contents are supplied under the terms of the
+.\" Common Development and Distribution License ("CDDL"), version 1.0.
+.\" You may only use this file in accordance with the terms of version
+.\" 1.0 of the CDDL.
+.\"
+.\" A full copy of the text of the CDDL should have accompanied this
+.\" source.  A copy of the CDDL is also available via the Internet at
+.\" http://www.illumos.org/license/CDDL.
+.\"
+.\"
+.\" Copyright (c) 2014, Joyent, Inc. All Rights Reserved.
+.\"
+.Dd Dec 3, 2014
+.Dt EVENTFD 3C
+.Os
+.Sh NAME
+.Nm eventfd
+.Nd create a file descriptor for event notification
+.Sh SYNOPSIS
+.In sys/eventfd.h
+.Ft int
+.Fo eventfd
+.Fa "unsigned int initval"
+.Fa "int flags"
+.Fc
+.Sh DESCRIPTION
+The
+.Fn eventfd
+function creates an
+.Xr eventfd 5
+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.,
+.Xr poll 2 ,
+.Xr port_get 3C ,
+.Xr epoll_wait 3C Ns ).
+To dispose of the instance,
+.Xr close 2
+should be called on the file descriptor.
+.Pp
+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.)
+.Pp
 The \fIflags\fR argument specifies additional parameters for the
 instance, and can have any of the following values:
-
-.sp
-.ne 2
-.na
-\fBEFD_CLOEXEC\fR
-.ad
-.RS 12n
+.Bl -hang -width Ds
+.It Sy EFD_CLOEXEC
+.Bd -filled -compact
 Instance will be closed upon an
-\fBexec\fR(2); see \fBopen\fR(2)'s description of \fBO_CLOEXEC\fR.
-.RE
-
-.sp
-.ne 2
-.na
-\fBEFD_NONBLOCK\fR
-.ad
-.RS 12n
-Instance will be set to be non-blocking.  A \fBread\fR(2) on an
-\fBeventfd\fR instance that has been initialized with
-\fBEFD_NONBLOCK\fR will return \fBEAGAIN\fR in lieu of blocking if the
-count associated with the instance is zero.
-.RE
-
-.sp
-.ne 2
-.na
-\fBEFD_SEMAPHORE\fR
-.ad
-.RS 12n
-Provide counting semaphore semantics whereby a \fBread\fR(2) will 
-atomically decrement rather than atomically clear the count when it
-becomes non-zero. See below for details on \fBread\fR(2) semantics.
-.RE
-
-.sp
-The following operations can be performed upon an \fBeventfd\fR instance:
-
-.sp
-.ne 2
-.na
-\fBread\fR(2)
-.ad
-.RS 12n
+.Xr exec 2 ;
+see
+.Xr open 2 Ns 's
+description of
+.Sy O_CLOEXEC .
+.Ed
+.It Sy EFD_NONBLOCK
+.Bd -filled -compact
+Instance will be set to be non-blocking.  A
+.Xr read 2
+on an
+.Sy eventfd
+instance that has been initialized with
+.Sy EFD_NONBLOCK
+will return
+.Sy EAGAIN
+in lieu of blocking if the count associated with the instance is zero.
+.Ed
+.It EFD_SEMAPHORE
+.Bd -filled -compact
+Provide counting semaphore semantics whereby a
+.Xr read 2
+will atomically decrement rather than atomically clear the count when it
+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
+instance:
+.Bl -hang -width Ds
+.It Sy read(2)
+.Bd -filled -compact
 Atomically reads and modifies the value of the 64-bit counter associated
 with the instance.  The precise semantics
-of \fBread\fR(2) depend on the disposition of \fBEFD_SEMAPHORE\fR with
-respect to the instance: if \fBEFD_SEMAPHORE\fR was set when the instance
-was created, \fBread\fR(2) will \fIatomically decrement\fR the counter if
-(and when)
-it is non-zero, copying the value 1 to the eight byte buffer passed to
-the system call; if \fBEFD_SEMAPHORE\fR was not set, \fBread\fR(2) will
-\fIatomically clear\fR 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.  In either case, \fBread\fR(2) will block if the counter is
-zero (or return \fBEAGAIN\fR if the instance was created with
-\fBEFD_NONBLOCK\fR). If the buffer specified to \fBread\fR(2) is less than
-eight bytes in length, \fBEINVAL\fR will be returned.
-
-.RE
-
-.sp
-.ne 2
-.na
-\fBwrite\fR(2)
-.ad
-.RS 12n
+of
+.Xr read 2
+depend on the disposition of
+.Sy EFD_SEMAPHORE
+with
+respect to the instance: if
+.Sy EFD_SEMAPTHORE
+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
+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.  In either case,
+.Xr read 2
+will block if the counter is
+zero (or return
+.Sy EAGAIN
+if the instance was created with
+.Sy EFD_NONBLOCK Ns ).
+If the buffer specified to
+.Xr read 2
+is less than
+eight bytes in length,
+.Sy EINVAL
+will be returned.
+.Ed
+.It Sy write(2)
+.Bd -filled -compact
 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 \fBwrite\fR(2) will block until the value would not overflow
-(or return \fBEAGAIN\fR if the instance was created with
-\fBEFD_NONBLOCK\fR).  If the buffer specified to \fBwrite\fR(2) is less than
-eight bytes in length, \fBEINVAL\fR will be returned.
-
-.RE
-
-.sp
-.ne 2
-.na
-\fBpoll\fR(2), \fBport_get\fR(3C), \fBepoll_wait\fR(3C)
-.ad
-.RS 12n
+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 ).
+If the buffer specified to
+.Xr write 2
+is less than eight bytes in length,
+.Sy EINVAL
+will be returned.
+.Ed
+.It Sy poll(2), port_get(3C), epoll_wait(3C)
+.Bd -filled -compact
 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, \fBPOLLIN\fR
-and \fBPOLLRDNORM\fR will be set; if the value 1 can be added the value
-without blocking, \fBPOLLOUT\fR and \fBPOLLWRNORM\fR will be set.
-.RE
-
-.SH RETURN VALUES
-.sp
-.LP
+If the 64-bit value associated with the instance is non-zero,
+.Sy POLLIN
+and
+.Sy POLLRDNORM
+will be set; if the value 1 can be added the value
+without blocking,
+.Sy POLLOUT
+and
+.Sy POLLWRNORM
+will be set.
+.Ed
+.El
+.Sh RETURN VALUES
 Upon succesful completion, a file descriptor associated with the instance
-is returned. Otherwise, -1 is returned and errno
+is returned. Otherwise,
+.Sy -1 is returned and
+.Sy errno
 is set to indicate the error.
-.SH ERRORS
-.sp
-.LP
-The \fBeventfd()\fR function will fail if:
-.sp
-.ne 2
-.na
-\fB\fBEINVAL\fR\fR
-.ad
-.RS 10n
-The \fIflags\fR are invalid.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBEMFILE\fR\fR
-.ad
-.RS 10n
-There are currently {\fBOPEN_MAX\fR} file descriptors open in the calling
-process.
-.RE
-
-.SH SEE ALSO
-.sp
-.LP
-\fBpoll\fR(2), \fBport_get\fR(3C), \fBepoll_wait\fR(3C), \fBeventfd\fR(5)
-
+.Sh ERRORS
+The
+.Fn eventfd
+function will fail if:
+.Bl -tag -width Er
+.It Er EINVAL
+The
+.Fa flags
+are invalid.
+.It Er EMFILE
+There are currently
+.Pf { Sy OPEN_MAX Ns }
+file descriptors open in the calling process.
+.El
+.Sh SEE ALSO
+.Xr poll 2 ,
+.Xr port_get 3C ,
+.Xr epoll_wait 3C ,
+.Xr eventfd 5