KTR(9) BSD Kernel Developer's Manual KTR(9)NAME
KTR_INFO_MASTER, KTR_INFO, KTR_LOG — kernel tracing facility
SYNOPSIS
#include <sys/ktr.h>
extern int ktr_entries;
extern int ktr_verbose;
extern struct ktr_entry *ktr_buf[MAXCPU];
KTR_INFO_MASTER(master);
KTR_INFO(compile, master, name, maskbit, format, datasize);
KTR_LOG(info, arg ...);
DESCRIPTION
The ktr facility provides a circular buffer of events that can be logged
in a kprintf(9) style fashion. These events can then be dumped with
ddb(4), gdb(1) or ktrdump(8).
KTR_INFO_MASTER() declares a new master variable ktr_master_enable that
is used to turn on and off event logging.
The KTR_INFO() macro registers a new event name that will be controlled
by the master enable variable. Code for logging this event will be com‐
piled in when compile is defined. The format argument is a kprintf(9)
style format string used to build the text of the event log message while
datasize specifies the size of the data to be logged, either the total
size of the arguments required by the format string or the size of the
data pointer ptr. For logging a fixed string with KTR_INFO(), datasize
is 0. The maskbit is currently unused and can be set to 0.
Kernel events are logged via the KTR_LOG() macro. The info parameter is
an identifier of the format master_name. KTR_LOG() accepts zero or more
additional arg arguments as required by the format string passed to the
associated KTR_INFO() call.
The ktr_entries variable contains the number of entries in the ktr_buf
array. These variables are mostly useful for post-mortem crash dump
tools to locate the base of the circular trace buffer and its length.
The ktr_verbose variable stores the verbose flag that controls whether
events are logged to the console in addition to the event buffer.
EXAMPLES
This example demonstrates a simple usage of the KTR facility:
#include <sys/ktr.h>
...
#if !defined(KTR_FOO)
#define KTR_FOO KTR_ALL
#endif
KTR_INFO_MASTER(foo);
KTR_INFO(KTR_FOO, foo, func1, 0, "func1()", 0);
KTR_INFO(KTR_FOO, foo, func2, 1, "func2(%d)", sizeof(int));
...
void
func1(void)
{
KTR_LOG(foo_func1);
...
}
void
func2(int arg)
{
KTR_LOG(foo_func2, arg);
...
}
SEE ALSOgdb(1), ddb(4), ktr(4), ktrdump(8), kprintf(9)HISTORY
The ktr kernel tracing facility first appeared in BSD/OS 3.0 and was
imported into FreeBSD 5.0 and DragonFly 1.1. It was completely rewritten
by Matthew Dillon in DragonFly 1.3.
BSD January 8, 2008 BSD
