man.bsd.lv manual page server

Manual Page Search Parameters

KTR(9) Kernel Developer's Manual KTR(9)

KTR_INFO_MASTER, KTR_INFO_MASTER_EXTERN, KTR_INFO, KTR_LOG, KTR_COND_LOGkernel tracing facility

#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_MASTER_EXTERN(master);

KTR_INFO(compile, master, name, maskbit, format, type name, ...);

KTR_LOG(info, arg ...);

KTR_COND_LOG(info, cond, arg ...);

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).

() declares a new master variable ktr_master_enable that is used to turn on and off event logging. () is a convenience macro for declaring a master variable .

The () macro registers a new event name that will be controlled by the master enable variable. Code for logging this event will be compiled in when compile is defined. The format argument is a format string in the manner of kprintf(9) used to build the text of the event log message. The arguments required by the format string have to be specified with a type and a name. The maskbit is a bit number that determines which of the corresponding debug.ktr.*_enable sysctl's bits will enable logging of this event.

Kernel events are logged via the () 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 () macro is equivalent to KTR_LOG() except it logs only when the condition specified in cond evaluates to true.

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.

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()");
KTR_INFO(KTR_FOO, foo, func2, 1, "func2(%d)", int arg);
KTR_INFO(KTR_FOO, foo, func3, 2, "func3: arg positive: %d", int arg);

...

void
func1(void)
{
	KTR_LOG(foo_func1);
	...
}

void
func2(int arg)
{
	KTR_LOG(foo_func2, arg);
	...
}

void
func3(int arg)
{
	KTR_COND_LOG(foo_func3, arg >= 0, arg);
	...
}

gdb(1), ddb(4), ktr(4), ktrdump(8), kprintf(9)

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.

August 22, 2012 DragonFly-5.6.1