1.\" Copyright (c) 2001 John H. Baldwin <jhb@FreeBSD.org> 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD: src/share/man/man9/ktr.9,v 1.8 2005/03/08 01:37:36 hmp Exp $ 26.\" 27.Dd August 22, 2012 28.Dt KTR 9 29.Os 30.Sh NAME 31.Nm KTR_INFO_MASTER , 32.Nm KTR_INFO_MASTER_EXTERN , 33.Nm KTR_INFO , 34.Nm KTR_LOG , 35.Nm KTR_COND_LOG 36.Nd kernel tracing facility 37.Sh SYNOPSIS 38.In sys/ktr.h 39.Vt "extern int ktr_entries" ; 40.Vt "extern int ktr_verbose" ; 41.Vt "extern struct ktr_entry *ktr_buf[MAXCPU]" ; 42.Fn KTR_INFO_MASTER "master" 43.Fn KTR_INFO_MASTER_EXTERN "master" 44.Fn KTR_INFO "compile" "master" "name" "maskbit" "format" "type name" "..." 45.Fn KTR_LOG "info" "arg ..." 46.Fn KTR_COND_LOG "info" "cond" "arg ..." 47.Sh DESCRIPTION 48The 49.Nm ktr 50facility provides a circular buffer of events that can be logged in a 51.Xr kprintf 9 52style fashion. 53These events can then be dumped with 54.Xr ddb 4 , 55.Xr gdb 1 56or 57.Xr ktrdump 8 . 58.Pp 59.Fn KTR_INFO_MASTER 60declares a new master variable 61.Dv ktr Ns _ Ns Fa master Ns _ Ns Dv enable 62that is used to turn on and off event logging. 63.Fn KTR_INFO_MASTER_EXTERN 64is a convenience macro for declaring a master variable 65.Sy extern . 66.Pp 67The 68.Fn KTR_INFO 69macro registers a new event 70.Fa name 71that will be controlled by the 72.Fa master 73enable variable. 74Code for logging this event will be compiled in when 75.Fa compile 76is defined. 77The 78.Fa format 79argument is a format string in the manner of 80.Xr kprintf 9 81used to build the text of the event log message. 82The arguments required by the format string have to be specified with a 83.Fa type 84and a 85.Fa name . 86The 87.Fa maskbit 88is a bit number that determines which of the corresponding 89.Va debug.ktr.*_enable 90sysctl's bits will enable logging of this event. 91.Pp 92Kernel events are logged via the 93.Fn KTR_LOG 94macro. 95The 96.Fa info 97parameter is an identifier of the format 98.Fa master Ns _ Ns Fa name . 99.Fn KTR_LOG 100accepts zero or more additional 101.Fa arg 102arguments as required by the 103.Fa format 104string passed to the associated 105.Fn KTR_INFO 106call. 107.Pp 108The 109.Fn KTR_COND_LOG 110macro is equivalent to 111.Fn KTR_LOG 112except it logs only when the condition specified in 113.Fa cond 114evaluates to true. 115.Pp 116The 117.Va ktr_entries 118variable contains the number of entries in the 119.Va ktr_buf 120array. 121These variables are mostly useful for post-mortem crash dump tools to locate 122the base of the circular trace buffer and its length. 123.Pp 124The 125.Va ktr_verbose 126variable stores the verbose flag that controls whether events are logged to 127the console in addition to the event buffer. 128.Sh EXAMPLES 129This example demonstrates a simple usage of the KTR facility: 130.Pp 131.Bd -literal -compact 132#include <sys/ktr.h> 133 134\&... 135 136#if !defined(KTR_FOO) 137#define KTR_FOO KTR_ALL 138#endif 139KTR_INFO_MASTER(foo); 140KTR_INFO(KTR_FOO, foo, func1, 0, "func1()"); 141KTR_INFO(KTR_FOO, foo, func2, 1, "func2(%d)", int arg); 142KTR_INFO(KTR_FOO, foo, func3, 2, "func3: arg positive: %d", int arg); 143 144\&... 145 146void 147func1(void) 148{ 149 KTR_LOG(foo_func1); 150 ... 151} 152 153void 154func2(int arg) 155{ 156 KTR_LOG(foo_func2, arg); 157 ... 158} 159 160void 161func3(int arg) 162{ 163 KTR_COND_LOG(foo_func3, arg >= 0, arg); 164 ... 165} 166.Ed 167.Sh SEE ALSO 168.Xr gdb 1 , 169.Xr ddb 4 , 170.Xr ktr 4 , 171.Xr ktrdump 8 , 172.Xr kprintf 9 173.Sh HISTORY 174The 175.Nm ktr 176kernel tracing facility first appeared in 177.Bsx 3.0 178and was imported into 179.Fx 5.0 180and 181.Dx 1.1 . 182It was completely rewritten by Matthew Dillon in 183.Dx 1.3 . 184