DragonFly On-Line Manual Pages


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

NAME

KTR_INFO_MASTER, KTR_INFO_MASTER_EXTERN, KTR_INFO, KTR_LOG, KTR_COND_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_MASTER_EXTERN(master); KTR_INFO(compile, master, name, maskbit, format, type name, ...); KTR_LOG(info, arg ...); KTR_COND_LOG(info, cond, 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. KTR_INFO_MASTER_EXTERN() is a convenience macro for declaring a master variable extern. 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 format string in the manner of kprintf(9) used to build the text of the event log mes- sage. 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 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_COND_LOG() 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.

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()"); 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); ... }

SEE ALSO

gdb(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. DragonFly 4.1 August 22, 2012 DragonFly 4.1