1.\" $OpenBSD: knote.9,v 1.10 2023/02/10 14:34:16 visa 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.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 20.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 21.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 22.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 23.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 24.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 25.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 26.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 27.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 28.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 29.\" POSSIBILITY OF SUCH DAMAGE. 30.\" 31.Dd $Mdocdate: February 10 2023 $ 32.Dt KNOTE 9 33.Os 34.Sh NAME 35.Nm knote , 36.Nm knote_locked 37.Nd raise kernel event 38.Sh SYNOPSIS 39.In sys/param.h 40.In sys/event.h 41.Ft void 42.Fn knote "struct klist *list" "long hint" 43.Ft void 44.Fn knote_locked "struct klist *list" "long hint" 45.Sh DESCRIPTION 46The 47.Fn knote 48and 49.Fn knote_locked 50functions provide a hook into the kqueue kernel event notification 51mechanism to allow sections of the kernel to raise a kernel event 52in the form of a 53.Sq knote , 54which is a 55.Fa struct knote 56as defined in 57.In sys/event.h . 58.Pp 59.Fn knote 60takes a singly linked 61.Fa list 62of knotes, along with a 63.Fa hint 64(which is passed to the appropriate filter routine). 65.Fn knote 66then locks and walks the 67.Fa list 68making calls to the filter routine for each knote. 69As each knote contains a reference to the data structure that it is 70attached to, the filter may choose to examine the data structure in 71deciding whether an event should be reported. 72The 73.Fa hint 74is used to pass in additional information, which may not be present in 75the data structure that the filter examines. 76.Pp 77If the filter decides that the event should be returned, it returns a 78non-zero value and 79.Fn knote 80links the knote onto the tail end of the active list in the 81corresponding kqueue for the application to retrieve. 82If the knote is already on the active list, no action is taken, but the 83call to the filter occurs in order to provide an opportunity for the 84filter to record the activity. 85.Pp 86.Fn knote_locked 87is like 88.Fn knote 89but assumes that the 90.Fa list 91is already locked. 92.Pp 93.Fn knote 94and 95.Fn knote_locked 96must not be called from interrupt contexts running at an interrupt 97priority level higher than 98.Fn splsched . 99.\" .Sh ERRORS 100.Sh SEE ALSO 101.Xr kqueue 2 102.\" .Xr kfilter_register 9 103.Sh HISTORY 104The 105.Fn knote 106functions first appeared in 107.Fx 4.1 , 108and then in 109.Ox 2.9 . 110.Sh AUTHORS 111The 112.Fn kqueue 113system was written by 114.An Jonathan Lemon Aq Mt jlemon@FreeBSD.org . 115