poll() as a system call

2 files changed, 206 insertions, 6 deletions

diff --git a/lib/libc/sys/Makefile.inc b/lib/libc/sys/Makefile.inc
index 0f308371e19..179e6a92ab8 100644
--- a/lib/libc/sys/Makefile.inc
+++ b/lib/libc/sys/Makefile.inc
@@ -100,12 +100,13 @@ MAN+=	accept.2 access.2 acct.2 adjtime.2 bind.2 brk.2 chdir.2 chflags.2 \
 	listen.2 lseek.2 mkdir.2 mkfifo.2 mknod.2 madvise.2 mincore.2 \
 	minherit.2 mlock.2 \
 	mmap.2 mount.2 mprotect.2 msync.2 munmap.2 nfssvc.2 open.2 pathconf.2 \
-	pipe.2 profil.2 ptrace.2 quotactl.2 read.2 readlink.2 reboot.2 recv.2 \
-	rename.2 revoke.2 rfork.2 rmdir.2 select.2 send.2 setgroups.2 setpgid.2 \
-	setsid.2 setuid.2 shutdown.2 sigaction.2 sigaltstack.2 sigpending.2 \
-	sigprocmask.2 sigreturn.2 sigstack.2 sigsuspend.2 socket.2 \
-	socketpair.2 stat.2 statfs.2 swapon.2 symlink.2 sync.2 sysarch.2 \
-	syscall.2 truncate.2 umask.2 unlink.2 utimes.2 vfork.2 wait.2 write.2
+	pipe.2 profil.2 poll.2 ptrace.2 quotactl.2 read.2 readlink.2 reboot.2 \
+	recv.2 rename.2 revoke.2 rfork.2 rmdir.2 select.2 send.2 setgroups.2 \
+	setpgid.2 setsid.2 setuid.2 shutdown.2 sigaction.2 sigaltstack.2 \
+	sigpending.2 sigprocmask.2 sigreturn.2 sigstack.2 sigsuspend.2 \
+	socket.2 socketpair.2 stat.2 statfs.2 swapon.2 symlink.2 sync.2 \
+	sysarch.2 syscall.2 truncate.2 umask.2 unlink.2 utimes.2 vfork.2 \
+	wait.2 write.2
 
 MAN+=	msgctl.2 shmctl.2 shmat.2 semop.2 semget.2 semctl.2 msgsnd.2 msgrcv.2 \
 	msgget.2 shmget.2
diff --git a/lib/libc/sys/poll.2 b/lib/libc/sys/poll.2
new file mode 100644
index 00000000000..f07df83eaec
--- /dev/null
+++ b/lib/libc/sys/poll.2
@@ -0,0 +1,199 @@
+.\"
+.\" Copyright (c) 1994 Jason R. Thorpe
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"	This product includes software developed by Jason R. Thorpe.
+.\" 4. The name of the author may not be used to endorse or promote products
+.\"    derived from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
+.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\"
+.Dd December 13, 1994
+.Dt POLL 2
+.Os
+.Sh NAME
+.Nm poll
+.Nd synchronous I/O multiplexing
+.Sh SYNOPSIS
+.Fd #include <poll.h>
+.Ft int
+.Fn poll "struct pollfd *fds" "int nfds" "int timeout"
+.Sh DESCRIPTION
+.Fn Poll
+provides a mechanism for reporting I/O conditions across a set of file
+descriptors.
+.Pp
+The arguments are as follows:
+.Bl -tag -width timeout
+.It Pa fds
+Points to an array of
+.Nm pollfd
+structures, which are defined as:
+.Bd -literal -offset indent
+struct pollfd {
+	int fd;
+	short events;
+	short revents;
+};
+.Ed
+.Pp
+The
+.Pa fd
+member is an open file descriptor.  The
+.Pa events
+and
+.Pa revents
+members are bitmasks of conditions to monitor and conditions found,
+respectively.
+.It Pa nfds
+The number of
+.Nm pollfd
+structures in the array.
+.It Pa timeout
+Maximum interval to wait for the poll to complete, in milliseconds.  If
+this value is 0, then
+.Fn poll
+will return immediately.  If this value is less than 0,
+.Fn poll
+will block indefinitely until a condition is found.
+.El
+.Pp
+The calling process sets the
+.Pa events
+bitmask and
+.Fn poll
+sets the
+.Pa revents
+bitmask.  Each call to
+.Fn poll
+resets the
+.Pa revents
+bitmask for accuracy.  The condition flags in the bitmasks are defined as:
+.Bl -tag -width POLLRDNORM
+.It Nm POLLIN
+Data is available on the file descriptor for reading.
+.It Nm POLLNORM
+Same as
+.Nm POLLIN .
+.It Nm POLLPRI
+Same as
+.Nm POLLIN .
+.It Nm POLLOUT
+Data can be written to the file descriptor without blocking.
+.It Nm POLLERR
+This flag is not used in this implementation and is provided only for source
+code compatibility.
+.It Nm POLLHUP
+The file descriptor was valid before the polling process and invalid after.
+Presumably, this means that the file descriptor was closed sometime during
+the poll.
+.It Nm POLLNVAL
+The corresponding file descriptor is invalid.
+.It Nm POLLRDNORM
+Same as
+.Nm POLLIN .
+.It Nm POLLRDBAND
+Same as
+.Nm POLLIN .
+.It Nm POLLWRNORM
+Same as
+.Nm POLLOUT .
+.It Nm POLLWRBAND
+Same as
+.Nm POLLOUT .
+.It Nm POLLMSG
+This flag is not used in this implementation and is provided only for source
+code compatibility.
+.El
+.Pp
+All flags except
+.Nm POLLIN ,
+.Nm POLLOUT ,
+and their synonyms are for use only in the
+.Pa revents
+member of the
+.Nm pollfd
+structure.  An attempt to set any of these flags in the
+.Pa events
+member will generate an error condition.
+.Pp
+In addition to I/O multiplexing,
+.Fn poll
+can be used to generate simple timeouts.  This functionality may be achieved
+by passing a NULL pointer for
+.Pa fds .
+.Sh WARNINGS
+Since this implementation is a wrapper around
+.Fn select ,
+functionality is limited to such.  There is no differentiation between
+standard and priority messages in the read or write queues.
+.Pp
+The
+.Nm POLLHUP
+flag is only a close approximation and may not always be accurate.
+.Sh RETURN VALUES
+Upon error,
+.Fn poll
+returns a -1 and sets the global variable
+.Pa errno
+to indicate the error.  If the timeout interval was reached before any events
+occurred, a 0 is returned.  Otherwise,
+.Fn poll
+returns the number of file descriptors for which
+.Pa revents
+is non-zero.
+.Sh ERRORS
+.Fn Poll
+will fail if:
+.Bl -tag -width "EINVAL   "
+.It Bq Er EINVAL
+.Pa nfds
+was either a negative number or greater than the number of available
+file descriptors.
+.It Bq Er EINVAL
+An invalid flags was set in the
+.Pa events
+member of the
+.Nm pollfd
+structure.
+.It Bq Er EINVAL
+The timeout passed to
+.Fn select
+was too large.
+.It Bq Er EAGAIN
+Resource allocation failed inside of
+.Fn poll .
+Subsequent calls to
+.Fn poll
+may succeed.
+.It Bq Er EINTR
+.Fn Select
+caught a signal during the polling process.
+.El
+.Sh SEE ALSO
+.Xr sysconf 3 ,
+.Xr select 2
+.Sh HISTORY
+A
+.Fn poll
+system call appeared in
+.At V