1*c78098b6Svisa.\" $OpenBSD: knote.9,v 1.10 2023/02/10 14:34:16 visa Exp $ 26bf776b2Smickey.\" $NetBSD: knote.9,v 1.9 2003/04/16 13:35:29 wiz Exp $ 36bf776b2Smickey.\" 46bf776b2Smickey.\" Copyright (c) 2001, 2002, 2003 The NetBSD Foundation, Inc. 56bf776b2Smickey.\" All rights reserved. 66bf776b2Smickey.\" 76bf776b2Smickey.\" This documentation is derived from text contributed by 86bf776b2Smickey.\" Luke Mewburn. 96bf776b2Smickey.\" 106bf776b2Smickey.\" Redistribution and use in source and binary forms, with or without 116bf776b2Smickey.\" modification, are permitted provided that the following conditions 126bf776b2Smickey.\" are met: 136bf776b2Smickey.\" 1. Redistributions of source code must retain the above copyright 146bf776b2Smickey.\" notice, this list of conditions and the following disclaimer. 156bf776b2Smickey.\" 2. Redistributions in binary form must reproduce the above copyright 166bf776b2Smickey.\" notice, this list of conditions and the following disclaimer in the 176bf776b2Smickey.\" documentation and/or other materials provided with the distribution. 186bf776b2Smickey.\" 196bf776b2Smickey.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 206bf776b2Smickey.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 216bf776b2Smickey.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 226bf776b2Smickey.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 236bf776b2Smickey.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 246bf776b2Smickey.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 256bf776b2Smickey.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 266bf776b2Smickey.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 276bf776b2Smickey.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 286bf776b2Smickey.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 296bf776b2Smickey.\" POSSIBILITY OF SUCH DAMAGE. 306bf776b2Smickey.\" 31*c78098b6Svisa.Dd $Mdocdate: February 10 2023 $ 326bf776b2Smickey.Dt KNOTE 9 336bf776b2Smickey.Os 346bf776b2Smickey.Sh NAME 356bf776b2Smickey.Nm knote , 36*c78098b6Svisa.Nm knote_locked 376bf776b2Smickey.Nd raise kernel event 386bf776b2Smickey.Sh SYNOPSIS 39dddd2645Sschwarze.In sys/param.h 40dddd2645Sschwarze.In sys/event.h 416bf776b2Smickey.Ft void 426bf776b2Smickey.Fn knote "struct klist *list" "long hint" 43*c78098b6Svisa.Ft void 44*c78098b6Svisa.Fn knote_locked "struct klist *list" "long hint" 456bf776b2Smickey.Sh DESCRIPTION 466bf776b2SmickeyThe 476bf776b2Smickey.Fn knote 48*c78098b6Svisaand 49*c78098b6Svisa.Fn knote_locked 50*c78098b6Svisafunctions provide a hook into the kqueue kernel event notification 516bf776b2Smickeymechanism to allow sections of the kernel to raise a kernel event 526bf776b2Smickeyin the form of a 536bf776b2Smickey.Sq knote , 546bf776b2Smickeywhich is a 556bf776b2Smickey.Fa struct knote 566bf776b2Smickeyas defined in 57369bef3aSschwarze.In sys/event.h . 586bf776b2Smickey.Pp 596bf776b2Smickey.Fn knote 606bf776b2Smickeytakes a singly linked 616bf776b2Smickey.Fa list 629d7e074bSjmcof knotes, along with a 636bf776b2Smickey.Fa hint 646bf776b2Smickey(which is passed to the appropriate filter routine). 656bf776b2Smickey.Fn knote 66*c78098b6Svisathen locks and walks the 676bf776b2Smickey.Fa list 686bf776b2Smickeymaking calls to the filter routine for each knote. 696bf776b2SmickeyAs each knote contains a reference to the data structure that it is 706bf776b2Smickeyattached to, the filter may choose to examine the data structure in 716bf776b2Smickeydeciding whether an event should be reported. 726bf776b2SmickeyThe 736bf776b2Smickey.Fa hint 746bf776b2Smickeyis used to pass in additional information, which may not be present in 756bf776b2Smickeythe data structure that the filter examines. 766bf776b2Smickey.Pp 776bf776b2SmickeyIf the filter decides that the event should be returned, it returns a 786bf776b2Smickeynon-zero value and 796bf776b2Smickey.Fn knote 806bf776b2Smickeylinks the knote onto the tail end of the active list in the 816bf776b2Smickeycorresponding kqueue for the application to retrieve. 826bf776b2SmickeyIf the knote is already on the active list, no action is taken, but the 836bf776b2Smickeycall to the filter occurs in order to provide an opportunity for the 846bf776b2Smickeyfilter to record the activity. 856bf776b2Smickey.Pp 86*c78098b6Svisa.Fn knote_locked 87*c78098b6Svisais like 886bf776b2Smickey.Fn knote 89*c78098b6Svisabut assumes that the 90*c78098b6Svisa.Fa list 91*c78098b6Svisais already locked. 92*c78098b6Svisa.Pp 93*c78098b6Svisa.Fn knote 94*c78098b6Svisaand 95*c78098b6Svisa.Fn knote_locked 966bf776b2Smickeymust not be called from interrupt contexts running at an interrupt 976bf776b2Smickeypriority level higher than 986bf776b2Smickey.Fn splsched . 996bf776b2Smickey.\" .Sh ERRORS 1006bf776b2Smickey.Sh SEE ALSO 1016bf776b2Smickey.Xr kqueue 2 1026bf776b2Smickey.\" .Xr kfilter_register 9 1036bf776b2Smickey.Sh HISTORY 1046bf776b2SmickeyThe 1056bf776b2Smickey.Fn knote 1066bf776b2Smickeyfunctions first appeared in 1076bf776b2Smickey.Fx 4.1 , 1086bf776b2Smickeyand then in 1093665c5c1Sjmc.Ox 2.9 . 1106bf776b2Smickey.Sh AUTHORS 1116bf776b2SmickeyThe 1126bf776b2Smickey.Fn kqueue 1136bf776b2Smickeysystem was written by 114f0641c22Sschwarze.An Jonathan Lemon Aq Mt jlemon@FreeBSD.org . 115