.\"     $NetBSD: select.9,v 1.5 2010/12/02 12:54:13 wiz Exp $
.\"
.\" Copyright (C) 2002 Chad David <davidc@acns.ab.ca>. 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(s), this list of conditions and the following disclaimer as
.\"    the first lines of this file unmodified other than the possible
.\"    addition of one or more copyright notices.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice(s), this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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.
.\"
.\" $FreeBSD: src/share/man/man9/selrecord.9,v 1.2 2002/05/30 13:29:17 ru Exp $
.\"
.\" FreeBSD: .Dd March 20, 2002
.Dd May 13, 2008
.Dt SELECT 9
.Os
.Sh NAME
.Nm seldestroy ,
.Nm selinit ,
.Nm selrecord ,
.Nm selnotify
.Nd select and poll subsystem
.Sh SYNOPSIS
.In sys/param.h
.In sys/select.h
.Ft void
.Fn seldestroy "struct selinfo *sip"
.Ft void
.Fn selinit "struct selinfo *sip"
.Ft void
.Fn selrecord "struct lwp *selector" "struct selinfo *sip"
.Ft void
.Fn selnotify "struct selinfo *sip" "int events" "long knhint"
.Sh DESCRIPTION
.Fn selinit
and
.Fn seldestroy
functions must be used to initialize and destroy the
.Va struct selinfo .
The
.Fn seldestroy
function may block.
.Pp
.Fn selrecord
and
.Fn selnotify
are used by device drivers to coordinate
with the kernel implementation of
.Xr select 2
and
.Xr poll 2 .
Each object that can be polled contains a
.Dv selinfo
record.
Device drivers provide locking for the
.Dv selinfo
record.
.Pp
.Fn selrecord
records that the calling thread is interested in events related to a given
object.
.Fn selrecord
should only be called when the poll routine determines that the object
is not ready for I/O: there are no events of interest pending.
The check for pending I/O and call to
.Fn selrecord
must be atomic.
Atomicity can be provided by holding the object's lock across the test
and call to
.Fn selrecord .
For non-MPSAFE drivers, the global
.Dv kernel_lock
is enough to provide atomicity.
.Pp
.Fn selnotify
is called by the underlying object handling code in order to notify any waiting
threads that an event of interest has occurred.
The same lock held across the poll method and call to
.Fn selrecord
must be held across the call to
.Fn selnotify .
The lock prevents an event of interest being signalled while a thread is
in the process of recording its interest.
.Pp
The
.Fa events
indicates which event happen.
Zero may be used if unknown.
.Pp
.Fn selnotify
also calls
.Fn KNOTE
passing
.Va knhint
as an argument.
.Sh CODE REFERENCES
The core of the select and poll subsystem implementation is in
.Pa sys/kern/sys_select.c .
Data structures and function prototypes are located in
.Pa sys/sys/select.h ,
.Pa sys/sys/poll.h
and
.Pa sys/sys/selinfo.h .
.Sh SEE ALSO
.Xr poll 2 ,
.Xr select 2 ,
.Xr knote 9