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