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.\" $DragonFly: src/share/man/man9/ktr.9,v 1.11 2008/01/08 17:45:43 swildner Exp $ 27.\" 28.Dd January 8, 2008 29.Dt KTR 9 30.Os 31.Sh NAME 32.Nm KTR_INFO_MASTER , 33.Nm KTR_INFO , 34.Nm KTR_LOG 35.Nd kernel tracing facility 36.Sh SYNOPSIS 37.In sys/ktr.h 38.Vt "extern int ktr_entries" ; 39.Vt "extern int ktr_verbose" ; 40.Vt "extern struct ktr_entry *ktr_buf[MAXCPU]" ; 41.Fn KTR_INFO_MASTER "master" 42.Fn KTR_INFO "compile" "master" "name" "maskbit" "format" "datasize" 43.Fn KTR_LOG "info" "arg ..." 44.Sh DESCRIPTION 45The 46.Nm ktr 47facility provides a circular buffer of events that can be logged in a 48.Xr kprintf 9 49style fashion. 50These events can then be dumped with 51.Xr ddb 4 , 52.Xr gdb 1 53or 54.Xr ktrdump 8 . 55.Pp 56.Fn KTR_INFO_MASTER 57declares a new master variable 58.Dv ktr Ns _ Ns Fa master Ns _ Ns Dv enable 59that is used to turn on and off event logging. 60.Pp 61The 62.Fn KTR_INFO 63macro registers a new event 64.Fa name 65that will be controlled by the 66.Fa master 67enable variable. 68Code for logging this event will be compiled in when 69.Fa compile 70is defined. 71The 72.Fa format 73argument is a 74.Xr kprintf 9 75style format string used to build the text of the event log message while 76.Fa datasize 77specifies the size of the data to be logged, either the total size of the 78arguments required by the 79.Fa format 80string or the size of the data pointer 81.Fa ptr . 82For logging a fixed string with 83.Fn KTR_INFO , 84.Fa datasize 85is 0. 86The 87.Fa maskbit 88is currently unused and can be set to 0. 89.Pp 90Kernel events are logged via the 91.Fn KTR_LOG 92macro. 93The 94.Fa info 95parameter is an identifier of the format 96.Fa master Ns _ Ns Fa name . 97.Fn KTR_LOG 98accepts zero or more additional 99.Fa arg 100arguments as required by the 101.Fa format 102string passed to the associated 103.Fn KTR_INFO 104call. 105.Pp 106The 107.Va ktr_entries 108variable contains the number of entries in the 109.Va ktr_buf 110array. 111These variables are mostly useful for post-mortem crash dump tools to locate 112the base of the circular trace buffer and its length. 113.Pp 114The 115.Va ktr_verbose 116variable stores the verbose flag that controls whether events are logged to 117the console in addition to the event buffer. 118.Sh EXAMPLES 119This example demonstrates a simple usage of the KTR facility: 120.Pp 121.Bd -literal -compact 122#include <sys/ktr.h> 123 124\&... 125 126#if !defined(KTR_FOO) 127#define KTR_FOO KTR_ALL 128#endif 129KTR_INFO_MASTER(foo); 130KTR_INFO(KTR_FOO, foo, func1, 0, "func1()", 0); 131KTR_INFO(KTR_FOO, foo, func2, 1, "func2(%d)", sizeof(int)); 132 133\&... 134 135void 136func1(void) 137{ 138 KTR_LOG(foo_func1); 139 ... 140} 141 142void 143func2(int arg) 144{ 145 KTR_LOG(foo_func2, arg); 146 ... 147} 148.Ed 149.Sh SEE ALSO 150.Xr gdb 1 , 151.Xr ddb 4 , 152.Xr ktr 4 , 153.Xr ktrdump 8 , 154.Xr kprintf 9 155.Sh HISTORY 156The 157.Nm ktr 158kernel tracing facility first appeared in 159.Bsx 3.0 160and was imported into 161.Fx 5.0 162and 163.Dx 1.1 . 164It was completely rewritten by Matthew Dillon in 165.Dx 1.3 . 166