Numerous adjustments to the recent rpcbind etc. changes.
[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 $
a45f658f 26.\" $DragonFly: src/share/man/man9/ktr.9,v 1.11 2008/01/08 17:45:43 swildner Exp $
81540c2d 27.\"
a45f658f 28.Dd January 8, 2008
81540c2d
EN
29.Dt KTR 9
30.Os
31.Sh NAME
525aff02
SW
32.Nm KTR_INFO_MASTER ,
33.Nm KTR_INFO ,
3b813696 34.Nm KTR_LOG
81540c2d
EN
35.Nd kernel tracing facility
36.Sh SYNOPSIS
81540c2d 37.In sys/ktr.h
81540c2d 38.Vt "extern int ktr_entries" ;
81540c2d 39.Vt "extern int ktr_verbose" ;
525aff02
SW
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 ..."
81540c2d 44.Sh DESCRIPTION
525aff02
SW
45The
46.Nm ktr
47facility provides a circular buffer of events that can be logged in a
48.Xr kprintf 9
49style fashion.
cdbdd4f6
HP
50These events can then be dumped with
51.Xr ddb 4 ,
52.Xr gdb 1
81540c2d 53or
cdbdd4f6 54.Xr ktrdump 8 .
81540c2d 55.Pp
525aff02
SW
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.
81540c2d
EN
71The
72.Fa format
73argument is a
525aff02
SW
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
81540c2d 79.Fa format
525aff02
SW
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
3b813696 92macro.
525aff02
SW
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.
81540c2d
EN
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
81540c2d
EN
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
525aff02
SW
119This example demonstrates a simple usage of the KTR facility:
120.Pp
bd02a712 121.Bd -literal -compact
a45f658f 122#include <sys/ktr.h>
525aff02
SW
123
124\&...
125
a45f658f
SW
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
81540c2d 142void
a45f658f 143func2(int arg)
81540c2d 144{
a45f658f 145 KTR_LOG(foo_func2, arg);
81540c2d
EN
146 ...
147}
148.Ed
149.Sh SEE ALSO
525aff02
SW
150.Xr gdb 1 ,
151.Xr ddb 4 ,
152.Xr ktr 4 ,
153.Xr ktrdump 8 ,
154.Xr kprintf 9
81540c2d 155.Sh HISTORY
525aff02
SW
156The
157.Nm ktr
158kernel tracing facility first appeared in
81540c2d
EN
159.Bsx 3.0
160and was imported into
161.Fx 5.0
162and
163.Dx 1.1 .
525aff02
SW
164It was completely rewritten by Matthew Dillon in
165.Dx 1.3 .