1.\" $OpenBSD: knote.9,v 1.2 2003/07/24 09:28:21 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.In sys/event.h 47.Ft void 48.Fn knote "struct klist *list" "long hint" 49.Fn KNOTE "struct klist *list" "long hint" 50.Sh DESCRIPTION 51The 52.Fn knote 53function provides a hook into the kqueue kernel event notification 54mechanism to allow sections of the kernel to raise a kernel event 55in the form of a 56.Sq knote , 57which is a 58.Fa struct knote 59as defined in 60.Aq Pa sys/event.h . 61.Pp 62.Fn knote 63takes a singly linked 64.Fa list 65of knotes, along with with a 66.Fa hint 67(which is passed to the appropriate filter routine). 68.Fn knote 69then walks the 70.Fa list 71making calls to the filter routine for each knote. 72As each knote contains a reference to the data structure that it is 73attached to, the filter may choose to examine the data structure in 74deciding whether an event should be reported. 75The 76.Fa hint 77is used to pass in additional information, which may not be present in 78the data structure that the filter examines. 79.Pp 80If the filter decides that the event should be returned, it returns a 81non-zero value and 82.Fn knote 83links the knote onto the tail end of the active list in the 84corresponding kqueue for the application to retrieve. 85If the knote is already on the active list, no action is taken, but the 86call to the filter occurs in order to provide an opportunity for the 87filter to record the activity. 88.Pp 89.Fn knote 90must not be called from interrupt contexts running at an interrupt 91priority level higher than 92.Fn splsched . 93.Pp 94.Fn KNOTE 95is a macro that calls 96.Fn knote list hint 97if 98.Fa list 99is not empty. 100.\" .Sh ERRORS 101.Sh SEE ALSO 102.Xr kqueue 2 103.\" .Xr kfilter_register 9 104.Sh HISTORY 105The 106.Fn knote 107and 108.Fn KNOTE 109functions first appeared in 110.Fx 4.1 , 111and then in 112.Ox 2.9 . 113.Sh AUTHORS 114The 115.Fn kqueue 116system was written by 117.An Jonathan Lemon Aq jlemon@FreeBSD.org . 118