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 January 2, 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.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_MASTER_EXTERN "master" 43.Fn KTR_INFO "compile" "master" "name" "maskbit" "format" "type name" "..." 44.Fn KTR_LOG "info" "arg ..." 45.Sh DESCRIPTION 46The 47.Nm ktr 48facility provides a circular buffer of events that can be logged in a 49.Xr kprintf 9 50style fashion. 51These events can then be dumped with 52.Xr ddb 4 , 53.Xr gdb 1 54or 55.Xr ktrdump 8 . 56.Pp 57.Fn KTR_INFO_MASTER 58declares a new master variable 59.Dv ktr Ns _ Ns Fa master Ns _ Ns Dv enable 60that is used to turn on and off event logging. 61.Fn KTR_INFO_MASTER_EXTERN 62is a convenience macro for declaring a master variable 63.Sy extern . 64.Pp 65The 66.Fn KTR_INFO 67macro registers a new event 68.Fa name 69that will be controlled by the 70.Fa master 71enable variable. 72Code for logging this event will be compiled in when 73.Fa compile 74is defined. 75The 76.Fa format 77argument is a format string in the manner of 78.Xr kprintf 9 79used to build the text of the event log message. 80The arguments required by the format string have to be specified with a 81.Fa type 82and a 83.Fa name . 84The 85.Fa maskbit 86is a bit number that determines which of the corresponding 87.Va debug.ktr.*_enable 88sysctl's bits will enable logging of this event. 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()"); 131KTR_INFO(KTR_FOO, foo, func2, 1, "func2(%d)", int arg); 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