share/man/man9/select.9

   1 .\"     $NetBSD: select.9,v 1.2 2008/03/25 21:51:32 xtraeme 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
  53 and
  54 .Fn seldestroy
  55 functions must be used to initialize and destroy the
  56 .Va struct selinfo .
  57 The
  58 .Fn seldestroy
  59 function may block.
  60 .Pp
  61 .Fn selrecord
  62 and
  63 .Fn selnotify
  64 are used by device drivers to coordinate
  65 with the kernel implementation of
  66 .Xr select 2
  67 and
  68 .Xr poll 2 .
  69 Each object that can be polled contains a
  70 .Dv selinfo
  71 record.
  72 Device drivers provide locking for the
  73 .Dv selinfo
  74 record.
  75 .Pp
  76 .Fn selrecord
  77 records that the calling thread is interested in events related to a given
  78 object.
  79 .Fn selrecord
  80 should only be called when the poll routine determines that the object
  81 is not ready for I/O: there are no events of interest pending.
  82 The check for pending I/O and call to
  83 .Fn selrecord
  84 must be atomic.
  85 Atomicity can be provided by holding the object's lock across the test
  86 and call to
  87 .Fn selrecord .
  88 For non-MPSAFE drivers, the global
  89 .Dv kernel_lock
  90 is enough to provide atomicity.
  91 .Pp
  92 .Fn selnotify
  93 is called by the underlying object handling code in order to notify any waiting
  94 threads that an event of interest has occurred.
  95 The same lock held across the poll method and call to
  96 .Fn selrecord
  97 must be held across the call to
  98 .Fn selnotify .
  99 The lock prevents an event of interest being signalled while a thread is
 100 in the process of recording its interest.
 101 .Pp
 102 The
 103 .Fa events
 104 indicates which event happen.
 105 Zero may be used if unknown.
 106 .Pp
 107 .Fn selnotify
 108 also calls
 109 .Fn KNOTE
 110 passing
 111 .Va knhint
 112 as an argument.
 113 .Sh CODE REFERENCES
 114 This section describes places within the
 115 .Nx
 116 source tree where actual code implementing select and poll
 117 subsystem can be found.
 118 All pathnames are relative to
 119 .Pa /usr/src .
 120 .Pp
 121 The core of the select and poll subsystem implementation is in
 122 .Pa sys/kern/sys_select.c .
 123 Data structures and function prototypes are located in
 124 .Pa sys/sys/select.h ,
 125 .Pa sys/sys/poll.h
 126 and
 127 .Pa sys/sys/selinfo.h .
 128 .Sh SEE ALSO
 129 .Xr poll 2 ,
 130 .Xr select 2 ,
 131 .Xr knote 9