1.\" $OpenBSD: knote.9,v 1.4 2003/10/30 19:10:03 jmc Exp $ 2.\" $NetBSD: knote.9,v 1.9 2003/04/16 13:35:29 wiz Exp $ 3.\" 4.\" Copyright (c) 2001, 2002, 2003 The NetBSD Foundation, Inc. 5.\" All rights reserved. 6.\" 7.\" This documentation is derived from text contributed by 8.\" Luke Mewburn. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. All advertising materials mentioning features or use of this software 19.\" must display the following acknowledgement: 20.\" This product includes software developed by the NetBSD 21.\" Foundation, Inc. and its contributors. 22.\" 4. Neither the name of The NetBSD Foundation nor the names of its 23.\" contributors may be used to endorse or promote products derived 24.\" from this software without specific prior written permission. 25.\" 26.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 27.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 28.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 29.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 30.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 31.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 32.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 33.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 34.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 35.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 36.\" POSSIBILITY OF SUCH DAMAGE. 37.\" 38.Dd February 23, 2003 39.Dt KNOTE 9 40.Os 41.Sh NAME 42.Nm knote , 43.Nm KNOTE 44.Nd raise kernel event 45.Sh SYNOPSIS 46.Fd #include <sys/param.h> 47.Fd #include <sys/event.h> 48.Ft void 49.Fn knote "struct klist *list" "long hint" 50.Fn KNOTE "struct klist *list" "long hint" 51.Sh DESCRIPTION 52The 53.Fn knote 54function provides a hook into the kqueue kernel event notification 55mechanism to allow sections of the kernel to raise a kernel event 56in the form of a 57.Sq knote , 58which is a 59.Fa struct knote 60as defined in 61.Aq Pa sys/event.h . 62.Pp 63.Fn knote 64takes a singly linked 65.Fa list 66of knotes, along with a 67.Fa hint 68(which is passed to the appropriate filter routine). 69.Fn knote 70then walks the 71.Fa list 72making calls to the filter routine for each knote. 73As each knote contains a reference to the data structure that it is 74attached to, the filter may choose to examine the data structure in 75deciding whether an event should be reported. 76The 77.Fa hint 78is used to pass in additional information, which may not be present in 79the data structure that the filter examines. 80.Pp 81If the filter decides that the event should be returned, it returns a 82non-zero value and 83.Fn knote 84links the knote onto the tail end of the active list in the 85corresponding kqueue for the application to retrieve. 86If the knote is already on the active list, no action is taken, but the 87call to the filter occurs in order to provide an opportunity for the 88filter to record the activity. 89.Pp 90.Fn knote 91must not be called from interrupt contexts running at an interrupt 92priority level higher than 93.Fn splsched . 94.Pp 95.Fn KNOTE 96is a macro that calls 97.Fn knote list hint 98if 99.Fa list 100is not empty. 101.\" .Sh ERRORS 102.Sh SEE ALSO 103.Xr kqueue 2 104.\" .Xr kfilter_register 9 105.Sh HISTORY 106The 107.Fn knote 108and 109.Fn KNOTE 110functions first appeared in 111.Fx 4.1 , 112and then in 113.Ox 2.9 . 114.Sh AUTHORS 115The 116.Fn kqueue 117system was written by 118.An Jonathan Lemon Aq jlemon@FreeBSD.org . 119