ktr - add KTR_COND_LOG
[dragonfly.git] / share / man / man9 / ktr.9
CommitLineData
81540c2d
EN
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.\"
1bf4b486 25.\" $FreeBSD: src/share/man/man9/ktr.9,v 1.8 2005/03/08 01:37:36 hmp Exp $
81540c2d 26.\"
b0bbd261 27.Dd August 22, 2012
81540c2d
EN
28.Dt KTR 9
29.Os
30.Sh NAME
525aff02 31.Nm KTR_INFO_MASTER ,
9b8f7fea 32.Nm KTR_INFO_MASTER_EXTERN ,
525aff02 33.Nm KTR_INFO ,
b0bbd261
MC
34.Nm KTR_LOG ,
35.Nm KTR_COND_LOG
81540c2d
EN
36.Nd kernel tracing facility
37.Sh SYNOPSIS
81540c2d 38.In sys/ktr.h
81540c2d 39.Vt "extern int ktr_entries" ;
81540c2d 40.Vt "extern int ktr_verbose" ;
525aff02
SW
41.Vt "extern struct ktr_entry *ktr_buf[MAXCPU]" ;
42.Fn KTR_INFO_MASTER "master"
9b8f7fea 43.Fn KTR_INFO_MASTER_EXTERN "master"
8ad2d5de 44.Fn KTR_INFO "compile" "master" "name" "maskbit" "format" "type name" "..."
525aff02 45.Fn KTR_LOG "info" "arg ..."
b0bbd261 46.Fn KTR_COND_LOG "info" "cond" "arg ..."
81540c2d 47.Sh DESCRIPTION
525aff02
SW
48The
49.Nm ktr
50facility provides a circular buffer of events that can be logged in a
51.Xr kprintf 9
52style fashion.
cdbdd4f6
HP
53These events can then be dumped with
54.Xr ddb 4 ,
55.Xr gdb 1
81540c2d 56or
cdbdd4f6 57.Xr ktrdump 8 .
81540c2d 58.Pp
525aff02
SW
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.
9b8f7fea
SW
63.Fn KTR_INFO_MASTER_EXTERN
64is a convenience macro for declaring a master variable
65.Sy extern .
525aff02
SW
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.
81540c2d
EN
77The
78.Fa format
8ad2d5de 79argument is a format string in the manner of
525aff02 80.Xr kprintf 9
8ad2d5de
SW
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 .
525aff02
SW
86The
87.Fa maskbit
46da84fa
SW
88is a bit number that determines which of the corresponding
89.Va debug.ktr.*_enable
90sysctl's bits will enable logging of this event.
525aff02
SW
91.Pp
92Kernel events are logged via the
93.Fn KTR_LOG
3b813696 94macro.
525aff02
SW
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.
81540c2d
EN
107.Pp
108The
b0bbd261
MC
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
81540c2d
EN
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
81540c2d
EN
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
525aff02
SW
129This example demonstrates a simple usage of the KTR facility:
130.Pp
bd02a712 131.Bd -literal -compact
a45f658f 132#include <sys/ktr.h>
525aff02
SW
133
134\&...
135
a45f658f
SW
136#if !defined(KTR_FOO)
137#define KTR_FOO KTR_ALL
138#endif
139KTR_INFO_MASTER(foo);
8ad2d5de
SW
140KTR_INFO(KTR_FOO, foo, func1, 0, "func1()");
141KTR_INFO(KTR_FOO, foo, func2, 1, "func2(%d)", int arg);
b0bbd261 142KTR_INFO(KTR_FOO, foo, func3, 2, "func3: arg positive: %d", int arg);
a45f658f
SW
143
144\&...
145
146void
147func1(void)
148{
149 KTR_LOG(foo_func1);
150 ...
151}
152
81540c2d 153void
a45f658f 154func2(int arg)
81540c2d 155{
a45f658f 156 KTR_LOG(foo_func2, arg);
81540c2d
EN
157 ...
158}
b0bbd261
MC
159
160void
161func3(int arg)
162{
163 KTR_COND_LOG(foo_func3, arg >= 0, arg);
164 ...
165}
81540c2d
EN
166.Ed
167.Sh SEE ALSO
525aff02
SW
168.Xr gdb 1 ,
169.Xr ddb 4 ,
170.Xr ktr 4 ,
171.Xr ktrdump 8 ,
172.Xr kprintf 9
81540c2d 173.Sh HISTORY
525aff02
SW
174The
175.Nm ktr
176kernel tracing facility first appeared in
81540c2d
EN
177.Bsx 3.0
178and was imported into
179.Fx 5.0
180and
181.Dx 1.1 .
525aff02
SW
182It was completely rewritten by Matthew Dillon in
183.Dx 1.3 .