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