DragonFly On-Line Manual Pages

Search: Section:  

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 3.5                   August 22, 2012                  DragonFly 3.5

Search: Section: