OS-2893 add support for epoll

Reviewed by: Robert Mustacchi <rm@joyent.com>
Reviewed by: Jerry Jelinek <jerry.jelinek@joyent.com>

4 files changed, 546 insertions, 0 deletions

diff --git a/usr/src/man/man3c/Makefile b/usr/src/man/man3c/Makefile
index f3b6f18a7f..3056f2c923 100644
--- a/usr/src/man/man3c/Makefile
+++ b/usr/src/man/man3c/Makefile
@@ -13,6 +13,7 @@
 # Copyright 2011, Richard Lowe
 # Copyright 2013 Nexenta Systems, Inc.  All rights reserved.
 # Copyright 2013, OmniTI Computer Consulting, Inc. All rights reserved.
+# Copyright (c) 2014, Joyent, Inc.  All rights reserved.
 #
 
 include		$(SRC)/Makefile.master
@@ -106,6 +107,9 @@ MANFILES= 	__fbufsize.3c					\
 	 	enable_extended_FILE_stdio.3c			\
 	 	encrypt.3c					\
 	 	end.3c						\
+	 	epoll_create.3c					\
+	 	epoll_ctl.3c					\
+	 	epoll_wait.3c					\
 	 	err.3c						\
 	 	euclen.3c					\
 	 	exit.3c						\
@@ -706,6 +710,8 @@ MANLINKS=	FD_CLR.3c				\
 	 	endusershell.3c				\
 	 	endutent.3c				\
 	 	endutxent.3c				\
+	 	epoll_create1.3c			\
+	 	epoll_pwait.3c				\
 	 	erand48.3c				\
 	 	errno.3c				\
 	 	errx.3c					\
@@ -1435,6 +1441,9 @@ _etext.3c				:= LINKSRC = end.3c
 edata.3c				:= LINKSRC = end.3c
 etext.3c				:= LINKSRC = end.3c
 
+epoll_create1.3c			:= LINKSRC = epoll_create.3c
+epoll_pwait.3c				:= LINKSRC = epoll_wait.3c
+
 errx.3c					:= LINKSRC = err.3c
 verr.3c					:= LINKSRC = err.3c
 verrx.3c				:= LINKSRC = err.3c
diff --git a/usr/src/man/man3c/epoll_create.3c b/usr/src/man/man3c/epoll_create.3c
new file mode 100644
index 0000000000..87d0a85c38
--- /dev/null
+++ b/usr/src/man/man3c/epoll_create.3c
@@ -0,0 +1,106 @@
+'\" 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 EPOLL_CREATE 3C "Apr 17, 2014"
+.SH NAME
+epoll_create, epoll_create1 \- create an epoll instance
+.SH SYNOPSIS
+
+.LP
+.nf
+#include <sys/epoll.h>
+
+\fBint\fR \fBepoll_create\fR(\fBint\fR \fIsize\fR);
+.fi
+
+.LP
+.nf
+\fBint\fR \fBepoll_create1\fR(\fBint\fR \fIflags\fR);
+.fi
+
+.SH DESCRIPTION
+.sp
+.LP
+The \fBepoll_create()\fR and \fBepoll_create1()\fR functions both create an
+\fBepoll\fR(5) instance that can be operated upon via \fBepoll_ctl\fR(3C),
+\fBepoll_wait\fR(3C) and \fBepoll_pwait\fR(3C).  \fBepoll\fR instances are
+represented as file descriptors, and should be closed via \fBclose\fR(2).
+
+The only difference between the two functions is their signature;
+\fBepoll_create()\fR takes a size argument that
+is vestigal and is only meaningful in as much as it must be greater than
+zero, while \fBepoll_create1()\fR takes a flags argument that can have
+any of the following values:
+
+.sp
+.ne 2
+.na
+\fBEPOLL_CLOEXEC\fR
+.ad
+.RS 12n
+Instance should be closed upon an
+\fBexec\fR(2); see \fBopen\fR(2)'s description of \fBO_CLOEXEC\fR.
+.RE
+
+.SH RETURN VALUES
+.sp
+.LP
+Upon succesful completion, 0 is returned. Otherwise, -1 is returned and errno
+is set to indicate the error.
+.SH ERRORS
+.sp
+.LP
+The \fBepoll_create()\fR and \fBepoll_create1()\fR functions will fail if:
+.sp
+.ne 2
+.na
+\fB\fBEINVAL\fR\fR
+.ad
+.RS 10n
+Either the \fIsize\fR is zero (\fBepoll_create()\fR) or the \fIflags\fR
+are invalid (\fBepoll_create1()\fR).
+.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
+
+.sp
+.ne 2
+.na
+\fB\fBENFILE\fR\fR
+.ad
+.RS 10n
+The maximum allowable number of files is currently open in the system.
+.RE
+
+.sp
+.LP
+.SH NOTES
+.sp
+.LP
+
+The \fBepoll\fR(5) facility is implemented for purposes of offering
+compatibility for Linux-borne applications; native
+applications should continue to prefer using event ports via the
+\fBport_create\fR(3C), \fBport_associate\fR(3C) and \fBport_get\fR(3C)
+interfaces.  See \fBepoll\fR(5) for compatibility details and restrictions.
+.RE
+
+.SH SEE ALSO
+.sp
+.LP
+\fBepoll_ctl\fR(3C), \fBepoll_wait\fR(3C), \fBepoll\fR(5)
diff --git a/usr/src/man/man3c/epoll_ctl.3c b/usr/src/man/man3c/epoll_ctl.3c
new file mode 100644
index 0000000000..0cce6affa4
--- /dev/null
+++ b/usr/src/man/man3c/epoll_ctl.3c
@@ -0,0 +1,316 @@
+'\" 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 EPOLL_CTL 3C "Apr 17, 2014"
+.SH NAME
+epoll_ctl \- control an epoll instance
+.SH SYNOPSIS
+
+.LP
+.nf
+#include <sys/epoll.h>
+
+\fBint\fR \fBepoll_ctl\fR(\fBint\fR \fIepfd\fR, \fBint\fR \fIop\fR, \fBint\fR \fIfd\fR, \fBstruct epoll_event *\fR\fIevent\fR);
+.fi
+
+.SH DESCRIPTION
+.sp
+.LP
+The \fBepoll_ctl()\fR function executes the operation specified by
+\fIop\fR (as parameterized by \fIevent\fR) on the \fIepfd\fR epoll instance.
+Valid values for \fIop\fR:
+
+.sp
+.ne 2
+.na
+\fBEPOLL_CTL_ADD\fR
+.ad
+.RS 12n
+For the \fBepoll\fR(5) instance specified by \fIepfd\fR, 
+associate the file descriptor specified by \fIfd\fR with the event specified
+by \fIevent\fR.
+.RE
+
+.sp
+.ne 2
+.na
+\fBEPOLL_CTL_DEL\fR
+.ad
+.RS 12n
+For the \fBepoll\fR(5) instance specified by \fIepfd\fR, 
+remove all event associations for the file descriptor specified by \fIfd\fR.
+\fIevent\fR is ignored, and may be NULL.
+.RE
+
+.sp
+.ne 2
+.na
+\fBEPOLL_CTL_MOD\fR
+.ad
+.RS 12n
+For the \fBepoll\fR(5) instance specified by \fIepfd\fR, modify the event
+association for the file descriptor specified by \fIfd\fR to be that
+specified by \fIevent\fR.
+
+.RE
+
+The \fIevent\fR parameter has the following structure:
+
+.in +4
+.nf
+typedef union epoll_data {
+	void    *ptr;
+	int      fd;
+	uint32_t u32;
+	uint64_t u64;
+} epoll_data_t;
+
+struct epoll_event {
+	uint32_t     events;
+	epoll_data_t data;
+};
+.fi
+.in -4
+
+The \fIdata\fR field specifies the datum to
+be associated with the event and 
+will be returned via \fBepoll_wait\fR(3C).  
+The \fIevents\fR field denotes both the desired events (when specified via
+\fBepoll_ctl()\fR) and the events that have occurred (when returned via
+\fBepoll_wait\fR(3C)).
+In either case, the
+\fIevents\fR field is a bitmask constructed by a logical \fBOR\fR operation
+of any combination of the following event flags:
+
+.sp
+.ne 2
+.na
+\fBEPOLLIN\fR
+.as
+.RS 14n
+Data other than high priority data may be read without blocking. For streams,
+this flag is set in the returned \fIevents\fR even if the message is of
+zero length.
+.RE
+
+.sp
+.ne 2
+.na
+\fBEPOLLPRI\fR
+.as
+.RS 14n
+Normal data (priority band equals 0) may be read without blocking. For streams,
+this flag is set in the returned \fIevents\fR even if the message is of zero
+length.
+.RE
+
+.sp
+.ne 2
+.na
+\fBEPOLLOUT\fR
+.as
+.RS 14n
+Normal data (priority band equals 0) may be written without blocking.
+.RE
+
+.sp
+.ne 2
+.na
+\fBEPOLLRDNORM\fR
+.as
+.RS 14n
+Normal data (priority band equals 0) may be read without blocking. For streams,
+this flag is set in the returned \fIrevents\fR even if the message is of
+zero length.
+.RE
+
+.sp
+.ne 2
+.na
+\fBEPOLLRDBAND\fR
+.as
+.RS 14n
+Data from a non-zero priority band may be read without blocking. For streams,
+this flag is set in the returned \fIrevents\fR even if the message is of
+zero length.
+.RE
+
+.sp
+.ne 2
+.na
+\fBEPOLLWRNORM\fR
+.as
+.RS 14n
+The same as \fBEPOLLOUT\fR.
+.RE
+
+.sp
+.ne 2
+.na
+\fBEPOLLWRBAND\fR
+.as
+.RS 14n
+Priority data (priority band > 0) may be written.  This event only examines
+bands that have been written to at least once.
+.RE
+
+.sp
+.ne 2
+.na
+\fBEPOLLMSG\fR
+.as
+.RS 14n
+This exists only for backwards binary and source compatibility with Linux;
+it has no meaning and is ignored.
+.RE
+
+.sp
+.ne 2
+.na
+\fBEPOLLERR\fR
+.as
+.RS 14n
+An error has occurred on the device or stream.  This flag is only valid in the
+returned \fIevents\fR field.
+.RE
+
+.sp
+.ne 2
+.na
+\fBEPOLLHUP\fR
+.as
+.RS 14n
+A hangup has occurred on the stream. This event and \fBEPOLLOUT\fR are mutually
+exclusive; a stream can never be writable if a hangup has occurred. However,
+this event and  \fBEPOLLIN\fR, \fBEPOLLRDNORM\fR, \fBEPOLLRDBAND\fR,
+\fBEPOLLRDHUP\fR or
+\fBEPOLLPRI\fR are not mutually exclusive. This flag is only valid in the
+the \fIevents\fR field returned from \fBepoll_wait\fR(3C); it is not used
+in the \fIevents\fR field specified via \fBepoll_ctl()\fR.
+.RE
+
+.sp
+.ne 2
+.na
+\fBEPOLLRDHUP\fR
+.as
+.RS 14n
+The stream socket peer shutdown the writing half of the connection and no
+further data will be readable via the socket.  This event is not mutually
+exclusive with \fBEPOLLIN\fR.
+.RE
+
+.sp
+.ne 2
+.na
+\fBEPOLLWAKEUP\fR
+.as
+.RS 14n
+This exists only for backwards binary and source compatibility with Linux;
+it has no meaning and is ignored.
+.RE
+
+.sp
+.ne 2
+.na
+\fBEPOLLONESHOT\fR
+.as
+.RS 14n
+Sets the specified event to be in one-shot mode, whereby the event association
+with the \fBepoll\fR(5) instance specified by \fIepfd\fR is removed atomically
+as the event is returned via \fBepoll_wait\fR(3C).  Use of this mode allows
+for resolution of some of the
+races inherent in multithreaded use of \fBepoll_wait\fR(3C).
+.RE
+
+.sp
+.ne 2
+.na
+\fBEPOLLET\fR
+.as
+.RS 14n
+Sets the specified event to be edge-triggered mode instead of the default
+mode of level-triggered.  In this mode, events will be induced by
+transitions on an event source rather than the state of the event source.
+While perhaps superficially appealing, this mode introduces several new
+potential failure modes for user-level software and should be used
+with caution.
+.RE
+
+.SH RETURN VALUES
+.sp
+.LP
+Upon succesful completion, \fBepoll_ctl()\fR returns 0.
+If an error occurs, -1 is returned and errno is set to indicate
+the error.
+
+.SH ERRORS
+.sp
+.LP
+\fBepoll_ctl()\fR will fail if:
+.sp
+.ne 2
+.na
+\fB\fBEBADF\fR\fR
+.ad
+.RS 10n
+\fIepfd\fR is not a valid file descriptor.
+.RE
+
+.sp
+.ne 2
+.na
+\fB\fBEFAULT\fR\fR
+.ad
+.RS 10n
+The memory associated with \fIevent\fR was not mapped.
+.RE
+
+.sp
+.ne 2
+.na
+\fB\fBEEXIST\fR\fR
+.ad
+.RS 10n
+The operation specified was \fBEPOLL_CTL_ADD\fR and the specified file
+descriptor is already associated with an event for the specified
+\fBepoll\fR(5) instance.
+.RE
+
+.sp
+.ne 2
+.na
+\fB\fBENOENT\fR\fR
+.ad
+.RS 10n
+The operation specified was \fBEPOLL_CTL_MOD\fR or \fBEPOLL_CTL_DEL\fR and
+the specified file descriptor is not associated with an event for the
+specified \fBepoll\fR(5) instance.
+.RE
+
+.sp
+.LP
+.SH NOTES
+.sp
+.LP
+
+The \fBepoll\fR(5) facility is implemented for purposes of offering
+compatibility for Linux-borne applications; native
+applications should continue to prefer using event ports via the
+\fBport_create\fR(3C), \fBport_associate\fR(3C) and \fBport_get\fR(3C)
+interfaces.  See \fBepoll\fR(5) for compatibility details and restrictions.
+.RE
+
+.SH SEE ALSO
+.sp
+.LP
+\fBepoll_create\fR(3C), \fBepoll_wait\fR(3C),
+\fBport_create\fR(3C), \fBport_associate\fR(3C), \fBport_get\fR(3C),
+\fBepoll\fR(5)
diff --git a/usr/src/man/man3c/epoll_wait.3c b/usr/src/man/man3c/epoll_wait.3c
new file mode 100644
index 0000000000..6405c30b5d
--- /dev/null
+++ b/usr/src/man/man3c/epoll_wait.3c
@@ -0,0 +1,115 @@
+'\" 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 EPOLL_WAIT 3C "Apr 17, 2014"
+.SH NAME
+epoll_wait, epoll_pwait \- wait for epoll events
+.SH SYNOPSIS
+
+.LP
+.nf
+#include <sys/epoll.h>
+
+\fBint\fR \fBepoll_wait\fR(\fBint\fR \fIepfd\fR, \fBstruct epoll_event *\fR\fIevents\fR, 
+     \fBint\fR \fImaxevents\fR, \fBint\fR \fItimeout\fR);
+.fi
+
+.LP
+.nf
+\fBint\fR \fBepoll_pwait\fR(\fBint\fR \fIepfd\fR, \fBstruct epoll_event *\fR\fIevents\fR, 
+     \fBint\fR \fImaxevents\fR, \fBint\fR \fItimeout\fR,
+     \fBconst sigset_t *\fR\fIsigmask\fR);
+.fi
+
+.SH DESCRIPTION
+.sp
+.LP
+The \fBepoll_wait()\fR function waits for events on the \fBepoll\fR(5)
+instance specified by \fIepfd\fR.  The \fIevents\fR parameter must point to
+an array of \fImaxevents\fR \fIepoll_event\fR structures to be
+filled in with pending events.  The \fItimeout\fR argument specifies the
+number of milliseconds to wait for an event if none is pending.  A
+\fItimeout\fR of -1 denotes an infinite timeout.
+
+The \fBepoll_pwait()\fR is similar to \fBepoll_wait()\fR, but takes an
+additional \fIsigmask\fR argument that specifies the desired signal mask 
+when \fBepoll_pwait()\fR is blocked.  It is equivalent to atomically
+setting the signal mask, calling \fBepoll_wait()\fR, and restoring the
+signal mask upon return, and is therefore similar to the relationship
+between \fBselect\fR(3C) and \fBpselect\fR(3C).
+
+.SH RETURN VALUES
+.sp
+.LP
+Upon successful completion, \fBepoll_wait()\fR and \fBepoll_pwait()\fR return
+the number of events, or 0 if none was pending and \fItimeout\fR milliseconds
+elapsed.  If an error occurs, -1 is returned and errno is set to indicate
+the error.
+
+.SH ERRORS
+.sp
+.LP
+The \fBepoll_wait()\fR and \fBepoll_pwait()\fR functions will fail if:
+.sp
+.ne 2
+.na
+\fB\fBEBADF\fR\fR
+.ad
+.RS 10n
+\fIepfd\fR is not a valid file descriptor.
+.RE
+
+.sp
+.ne 2
+.na
+\fB\fBEFAULT\fR\fR
+.ad
+.RS 10n
+The memory associated with \fIevents\fR was not mapped or was not writable.
+.RE
+
+.sp
+.ne 2
+.na
+\fB\fBEINTR\fR\fR
+.ad
+.RS 10n
+A signal was received during the \fBepoll_wait()\fR or \fBepoll_pwait()\fR.
+.RE
+
+.sp
+.ne 2
+.na
+\fB\fBEINVAL\fR\fR
+.ad
+.RS 10n
+Either \fIepfd\fR is not a valid \fBepoll\fR(5) instance or \fImaxevents\fR
+is not greater than zero.
+.RE
+
+.sp
+.LP
+.SH NOTES
+.sp
+.LP
+
+The \fBepoll\fR(5) facility is implemented for purposes of offering
+compatibility for Linux-borne applications; native
+applications should continue to prefer using event ports via the
+\fBport_create\fR(3C), \fBport_associate\fR(3C) and \fBport_get\fR(3C)
+interfaces.  See \fBepoll\fR(5) for compatibility details and restrictions.
+.RE
+
+.SH SEE ALSO
+.sp
+.LP
+\fBepoll_create\fR(3C), \fBepoll_ctl\fR(3C),
+\fBport_create\fR(3C), \fBport_associate\fR(3C), \fBport_get\fR(3C), 
+\fBpselect\fR(3C), \fBepoll\fR(5)