1.\" $NetBSD: select.9,v 1.5 2010/12/02 12:54:13 wiz Exp $ 2.\" 3.\" Copyright (C) 2002 Chad David <davidc@acns.ab.ca>. All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice(s), this list of conditions and the following disclaimer as 10.\" the first lines of this file unmodified other than the possible 11.\" addition of one or more copyright notices. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice(s), this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY 17.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 18.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 19.\" DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY 20.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 21.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 22.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 23.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH 26.\" DAMAGE. 27.\" 28.\" $FreeBSD: src/share/man/man9/selrecord.9,v 1.2 2002/05/30 13:29:17 ru Exp $ 29.\" 30.\" FreeBSD: .Dd March 20, 2002 31.Dd May 13, 2008 32.Dt SELECT 9 33.Os 34.Sh NAME 35.Nm seldestroy , 36.Nm selinit , 37.Nm selrecord , 38.Nm selnotify 39.Nd select and poll subsystem 40.Sh SYNOPSIS 41.In sys/param.h 42.In sys/select.h 43.Ft void 44.Fn seldestroy "struct selinfo *sip" 45.Ft void 46.Fn selinit "struct selinfo *sip" 47.Ft void 48.Fn selrecord "struct lwp *selector" "struct selinfo *sip" 49.Ft void 50.Fn selnotify "struct selinfo *sip" "int events" "long knhint" 51.Sh DESCRIPTION 52.Fn selinit 53and 54.Fn seldestroy 55functions must be used to initialize and destroy the 56.Va struct selinfo . 57The 58.Fn seldestroy 59function may block. 60.Pp 61.Fn selrecord 62and 63.Fn selnotify 64are used by device drivers to coordinate 65with the kernel implementation of 66.Xr select 2 67and 68.Xr poll 2 . 69Each object that can be polled contains a 70.Dv selinfo 71record. 72Device drivers provide locking for the 73.Dv selinfo 74record. 75.Pp 76.Fn selrecord 77records that the calling thread is interested in events related to a given 78object. 79.Fn selrecord 80should only be called when the poll routine determines that the object 81is not ready for I/O: there are no events of interest pending. 82The check for pending I/O and call to 83.Fn selrecord 84must be atomic. 85Atomicity can be provided by holding the object's lock across the test 86and call to 87.Fn selrecord . 88For non-MPSAFE drivers, the global 89.Dv kernel_lock 90is enough to provide atomicity. 91.Pp 92.Fn selnotify 93is called by the underlying object handling code in order to notify any waiting 94threads that an event of interest has occurred. 95The same lock held across the poll method and call to 96.Fn selrecord 97must be held across the call to 98.Fn selnotify . 99The lock prevents an event of interest being signalled while a thread is 100in the process of recording its interest. 101.Pp 102The 103.Fa events 104indicates which event happen. 105Zero may be used if unknown. 106.Pp 107.Fn selnotify 108also calls 109.Fn KNOTE 110passing 111.Va knhint 112as an argument. 113.Sh CODE REFERENCES 114The core of the select and poll subsystem implementation is in 115.Pa sys/kern/sys_select.c . 116Data structures and function prototypes are located in 117.Pa sys/sys/select.h , 118.Pa sys/sys/poll.h 119and 120.Pa sys/sys/selinfo.h . 121.Sh SEE ALSO 122.Xr poll 2 , 123.Xr select 2 , 124.Xr knote 9 125