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