Changeset View
Changeset View
Standalone View
Standalone View
share/man/man9/ktr.9
Show All 17 Lines | |||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | ||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | ||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | ||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | ||||
.\" SUCH DAMAGE. | .\" SUCH DAMAGE. | ||||
.\" | .\" | ||||
.\" $FreeBSD$ | .\" $FreeBSD$ | ||||
.\" | .\" | ||||
.Dd March 26, 2021 | .Dd April 12, 2022 | ||||
.Dt KTR 9 | .Dt KTR 9 | ||||
.Os | .Os | ||||
.Sh NAME | .Sh NAME | ||||
.Nm CTR0 , CTR1 , CTR2 , CTR3 , CTR4 , CTR5 | .Nm CTR0 , CTR1 , CTR2 , CTR3 , CTR4 , CTR5 | ||||
.Nd kernel tracing facility | .Nd kernel tracing facility | ||||
.Sh SYNOPSIS | .Sh SYNOPSIS | ||||
.In sys/param.h | .In sys/param.h | ||||
.In sys/ktr.h | .In sys/ktr.h | ||||
.Vt "extern int ktr_cpumask" ; | .Vt "extern int ktr_cpumask" ; | ||||
.Vt "extern int ktr_entries" ; | .Vt "extern int ktr_entries" ; | ||||
.Vt "extern int ktr_extend" ; | .Vt "extern int ktr_extend" ; | ||||
.Vt "extern int ktr_mask" ; | .Vt "extern int ktr_mask" ; | ||||
.Vt "extern int ktr_verbose" ; | .Vt "extern int ktr_verbose" ; | ||||
.Vt "extern struct ktr_entry ktr_buf[]" ; | .Vt "extern struct ktr_entry ktr_buf[]" ; | ||||
.Ft void | .Ft void | ||||
.Fn CTR "u_int mask" "char *format" "..." | |||||
.Ft void | |||||
.Fn CTR0 "u_int mask" "char *format" | .Fn CTR0 "u_int mask" "char *format" | ||||
.Ft void | .Ft void | ||||
.Fn CTR1 "u_int mask" "char *format" "arg1" | .Fn CTR1 "u_int mask" "char *format" "arg1" | ||||
.Ft void | .Ft void | ||||
.Fn CTR2 "u_int mask" "char *format" "arg1" "arg2" | .Fn CTR2 "u_int mask" "char *format" "arg1" "arg2" | ||||
.Ft void | .Ft void | ||||
.Fn CTR3 "u_int mask" "char *format" "arg1" "arg2" "arg3" | .Fn CTR3 "u_int mask" "char *format" "arg1" "arg2" "arg3" | ||||
.Ft void | .Ft void | ||||
Show All 9 Lines | |||||
fashion. | fashion. | ||||
These events can then be dumped with | These events can then be dumped with | ||||
.Xr ddb 4 , | .Xr ddb 4 , | ||||
.Xr gdb 1 | .Xr gdb 1 | ||||
or | or | ||||
.Xr ktrdump 8 . | .Xr ktrdump 8 . | ||||
.Pp | .Pp | ||||
Events are created and logged in the kernel via the | Events are created and logged in the kernel via the | ||||
.Dv CTR | |||||
and | |||||
.Dv CTR Ns Ar x | .Dv CTR Ns Ar x | ||||
macros. | macros. | ||||
The first parameter is a mask of event types | The first parameter is a mask of event types | ||||
.Pq Dv KTR_* | .Pq Dv KTR_* | ||||
defined in | defined in | ||||
.In sys/ktr_class.h . | .In sys/ktr_class.h . | ||||
The event will be logged only if any of the event types specified in | The event will be logged only if any of the event types specified in | ||||
.Fa mask | .Fa mask | ||||
are enabled in the global event mask stored in | are enabled in the global event mask stored in | ||||
.Va ktr_mask . | .Va ktr_mask . | ||||
The | The | ||||
.Fa format | .Fa format | ||||
argument is a | argument is a | ||||
.Xr printf 9 | .Xr printf 9 | ||||
style format string used to build the text of the event log message. | style format string used to build the text of the event log message. | ||||
Following the | Following the | ||||
.Fa format | .Fa format | ||||
string are zero to five arguments referenced by | string are zero to six arguments referenced by | ||||
pauamma_gundo.com: Am I reading this right as saying that CTR itself can only handle 5 items to be output using… | |||||
Done Inline ActionsYes, though it's been six for several years. (The original macros from BSD/OS only allowed up to 5). jhb: Yes, though it's been six for several years. (The original macros from BSD/OS only allowed up… | |||||
.Fa format . | .Fa format . | ||||
Each event is logged with a file name and source line number of the | Each event is logged with a file name and source line number of the | ||||
originating CTR call, and a timestamp in addition to the log message. | originating CTR call, and a timestamp in addition to the log message. | ||||
.Pp | .Pp | ||||
The event is stored in the circular buffer with supplied arguments as is, | The event is stored in the circular buffer with supplied arguments as is, | ||||
and formatting is done at the dump time. | and formatting is done at the dump time. | ||||
Do not use pointers to the objects with limited lifetime, for instance, | Do not use pointers to the objects with limited lifetime, for instance, | ||||
strings, because the pointer may become invalid when buffer is printed. | strings, because the pointer may become invalid when buffer is printed. | ||||
.Pp | .Pp | ||||
Note that the different macros differ only in the number of arguments each | The | ||||
.Dv CTR Ns Ar x | |||||
macros differ only in the number of arguments each | |||||
one takes, as indicated by its name. | one takes, as indicated by its name. | ||||
.Pp | .Pp | ||||
The | The | ||||
.Va ktr_entries | .Va ktr_entries | ||||
variable contains the number of entries in the | variable contains the number of entries in the | ||||
.Va ktr_buf | .Va ktr_buf | ||||
array. | array. | ||||
These variables are mostly useful for post-mortem crash dump tools to locate | These variables are mostly useful for post-mortem crash dump tools to locate | ||||
Show All 35 Lines | |||||
.Sh SEE ALSO | .Sh SEE ALSO | ||||
.Xr ktr 4 , | .Xr ktr 4 , | ||||
.Xr ktrdump 8 | .Xr ktrdump 8 | ||||
.Sh HISTORY | .Sh HISTORY | ||||
The KTR kernel tracing facility first appeared in | The KTR kernel tracing facility first appeared in | ||||
.Bsx 3.0 | .Bsx 3.0 | ||||
and was imported into | and was imported into | ||||
.Fx 5.0 . | .Fx 5.0 . | ||||
.Pp | |||||
The | |||||
.Fn CTR | |||||
macro accepting a variable number of arguments first appeared in | |||||
.Fx 14.0 . | |||||
.Sh BUGS | .Sh BUGS | ||||
Currently there is one global buffer shared among all CPUs. | Currently there is one global buffer shared among all CPUs. | ||||
It might be profitable at some point in time to use per-CPU buffers instead | It might be profitable at some point in time to use per-CPU buffers instead | ||||
so that if one CPU halts or starts spinning, then the log messages it | so that if one CPU halts or starts spinning, then the log messages it | ||||
emitted just prior to halting or spinning will not be drowned out by events | emitted just prior to halting or spinning will not be drowned out by events | ||||
from the other CPUs. | from the other CPUs. | ||||
.Pp | .Pp | ||||
The arguments given in | The arguments given in | ||||
.Fn CTRx | .Fn CTRx | ||||
macros are stored as | macros are stored as | ||||
.Vt u_long , | .Vt u_long , | ||||
so do not pass arguments larger than size of an | so do not pass arguments larger than size of an | ||||
.Vt u_long | .Vt u_long | ||||
type. | type. | ||||
For example passing 64bit arguments on 32bit architectures will give incorrect | For example passing 64bit arguments on 32bit architectures will give incorrect | ||||
results. | results. |
Am I reading this right as saying that CTR itself can only handle 5 items to be output using the format argument, vararg or no vararg?