diff --git a/lib/libc/sys/Makefile.inc b/lib/libc/sys/Makefile.inc index c39128ccebce..9928b8ec985d 100644 --- a/lib/libc/sys/Makefile.inc +++ b/lib/libc/sys/Makefile.inc @@ -1,5 +1,5 @@ # @(#)Makefile.inc 8.3 (Berkeley) 10/24/94 -# $Id: Makefile.inc,v 1.37 1997/08/19 07:19:42 peter Exp $ +# $Id: Makefile.inc,v 1.38 1997/09/14 03:29:55 peter Exp $ # sys sources .PATH: ${.CURDIR}/../libc/${MACHINE}/sys ${.CURDIR}/../libc/sys @@ -105,7 +105,7 @@ MAN2+= sys/accept.2 sys/access.2 sys/acct.2 sys/adjtime.2 sys/bind.2 \ sys/mlock.2 \ sys/mmap.2 sys/mount.2 sys/mprotect.2 sys/msync.2 sys/munmap.2 \ sys/nanosleep.2 \ - sys/ptrace.2 sys/nfssvc.2 sys/open.2 sys/pathconf.2 sys/pipe.2 \ + sys/ptrace.2 sys/nfssvc.2 sys/open.2 sys/pathconf.2 sys/pipe.2 poll.2 \ sys/profil.2 sys/quotactl.2 sys/read.2 sys/readlink.2 sys/reboot.2 \ sys/recv.2 sys/rename.2 sys/revoke.2 sys/rfork.2 sys/rmdir.2 \ sys/rtprio.2 sys/select.2 \ diff --git a/lib/libc/sys/poll.2 b/lib/libc/sys/poll.2 new file mode 100644 index 000000000000..b6e6706e66cf --- /dev/null +++ b/lib/libc/sys/poll.2 @@ -0,0 +1,188 @@ +.\" $NetBSD: poll.2,v 1.3 1996/09/07 21:53:08 mycroft Exp $ +.\" $Id$ +.\" +.\" Copyright (c) 1996 Charles M. Hannum. 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 Charles M. Hannum. +.\" 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 SUCH DAMAGE. +.\" +.Dd September 7, 1996 +.Dt POLL 2 +.Os +.Sh NAME +.Nm poll +.Nd synchronous I/O multiplexing +.Sh SYNOPSIS +.Fd #include +.Fd #include +.Ft int +.Fn poll "struct pollfd *fds" "unsigned int nfds" "int timeout" +.Sh DESCRIPTION +.Fn Poll +examines a set of file descriptors to see if some of them are ready for +I/O. +The +.Fa fds +argument is a pointer to an array of pollfd structures as defined in +.Aq Pa poll.h +(shown below). The +.Fa nfds +argument determines the size of the +.Fa fds +array. +.Bd -literal +struct pollfd { + int fd; /* file descriptor */ + short events; /* events to look for */ + short revents; /* events returned */ +}; +.Ed +.Pp +The fields of +.Fa struct pollfd +are as follows: +.Bl -tag -width XXXrevents +.It fd +File descriptor to poll. +.It events +Events to poll for. (See below.) +.It revents +Events which may occur. (See below.) +.El +.Pp +The event bitmasks in +.Fa events +and +.Fa revents +have the following bits: +.Bl -tag -width XXXPOLLWRNORM +.It POLLIN +Data other than high priority data may be read without blocking. +.It POLLRDNORM +Normal data may be read without blocking. +.It POLLRDBAND +Data with a non-zero priority may be read without blocking. +.It POLLPRI +High priority data may be read without blocking. +.It POLLOUT +.It POLLWRNORM +Normal data may be written without blocking. +.It POLLWRBAND +Data with a non-zero priority may be written without blocking. +.It POLLERR +An exceptional condition has occured on the device or socket. This +flag is always checked, even if not present in the +.Fa events +bitmask. +.It POLLHUP +The device or socket has been disconnected. This flag is always +checked, even if not present in the +.Fa events +bitmask. Note that +POLLHUP +and +POLLOUT +should never be present in the +.Fa revents +bitmask at the same time. +.It POLLNVAL +The file descriptor is not open. This flag is always checked, even +if not present in the +.Fa events +bitmask. +.El +.Pp +If +.Fa timeout +is neither zero nor INFTIM (-1), it specifies a maximum interval to +wait for any file descriptor to become ready, in milliseconds. If +.Fa timeout +is INFTIM (-1), the poll blocks indefinitely. If +.Fa timeout +is zero, then +.Fn poll +will return without blocking. +.Sh RETURN VALUES +.Fn Poll +returns the number of descriptors that are ready for I/O, or -1 if an +error occured. If the time limit expires, +.Fn poll +returns 0. +If +.Fn poll +returns with an error, +including one due to an interrupted call, +the +.Fa fds +array will be unmodified. +.Sh COMPATIBILITY +This implementation differs from the historical one in that a given +file descriptor may not cause +.Fn poll +to return with an error. In cases where this would have happened in +the historical implementation (e.g. trying to poll a +.Xr revoke 2 ed +descriptor), this implementation instead copies the +.Fa events +bitmask to the +.Fa revents +bitmask. Attempting to perform I/O on this descriptor will then +return an error. This behaviour is believed to be more useful. +.Sh ERRORS +An error return from +.Fn poll +indicates: +.Bl -tag -width Er +.It Bq Er EFAULT +.Fa Fds +points outside the process's allocated address space. +.It Bq Er EINTR +A signal was delivered before the time limit expired and +before any of the selected events occurred. +.It Bq Er EINVAL +The specified time limit is negative. +.El +.Sh SEE ALSO +.Xr accept 2 , +.Xr connect 2 , +.Xr read 2 , +.Xr recv 2 , +.Xr select 2 , +.Xr send 2 , +.Xr write 2 +.Sh BUGS +The distinction between some of the fields in the +.Fa events +and +.Fa revents +bitmasks is really not useful without STREAMS. The fields are +defined for compatibility with existing software. +.Sh HISTORY +The +.Fn poll +function call appeared in +.At V . +This manual page and the core of the implementation was taken from +.Nx .