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