1.\" 2.\" SPDX-License-Identifier: BSD-2-Clause 3.\" 4.\" Copyright (c) 2025 Mateusz Piotrowski <0mp@FreeBSD.org> 5.\" 6.Dd July 14, 2025 7.Dt DTRACE_DTRACE 4 8.Os 9.Sh NAME 10.Nm dtrace_dtrace 11.Nd a DTrace provider for BEGIN, END, and ERROR probes 12.Sh SYNOPSIS 13.Nm dtrace Ns Cm :::BEGIN 14.Nm dtrace Ns Cm :::END 15.Nm dtrace Ns Cm :::ERROR 16.Sh DESCRIPTION 17The 18.Nm dtrace 19provider implements three special probes related to the life cycle of the 20DTrace program itself. 21.Ss dtrace:::BEGIN 22The 23.Nm dtrace Ns Cm :::BEGIN 24probe fires at the beginning of a 25.Xr dtrace 1 , 26program before tracing has begun. 27It provides a convenient place for initializing variables 28and printing column headers. 29.Pp 30Variables such as 31.Va stack 32or 33.Va execname 34cannot be relied upon in the execution context of the 35.Nm dtrace Ns Cm :::BEGIN 36probe. 37.Ss dtrace:::END 38The 39.Nm dtrace Ns Cm :::END 40probe fires at the end of a 41.Xr dtrace 1 42program, when all tracing has stopped. 43.Ss dtrace:::ERROR 44The 45.Nm dtrace Ns Cm :::ERROR 46probe fires when an unexpected runtime error occurs in another probe. 47.Pp 48The following table describes the arguments to 49.Nm dtrace Ns Cm :::ERROR . 50.Bl -column -offset indent "Argument" "Definition" 51.It Sy Argument Ta Sy Definition 52.It Fa arg1 Ta Enabled probe identifier (EPID) 53of the probe where the runtime error occurred 54.It Fa arg2 Ta Index of the action statement that caused the error 55.It Fa arg3 Ta DIF offset into the action if available (otherwise -1) 56.It Fa arg4 Ta Fault type 57.It Fa arg5 Ta Accessed address (or 0 if not applicable) when 58.Va arg4 59is of fault type 60.Dv DTRACEFLT_BADADDR , DTRACEFLT_BADALIGN , DTRACEFLT_KPRIV , 61or 62.Dv DTRACEFLT_UPRIV 63.El 64.Pp 65The fault types are: 66.Bl -tag -offset indent -width "DTRACEFLT_NOSCRATCH" -compact 67.It Dv DTRACEFLT_UNKNOWN 68Unknown fault 69.It Dv DTRACEFLT_BADADDR 70Bad address 71.It Dv DTRACEFLT_BADALIGN 72Bad alignment 73.It Dv DTRACEFLT_ILLOP 74Illegal operation 75.It Dv DTRACEFLT_DIVZERO 76Divide-by-zero 77.It Dv DTRACEFLT_NOSCRATCH 78Out of scratch space 79.It Dv DTRACEFLT_KPRIV 80Illegal kernel access 81.It Dv DTRACEFLT_UPRIV 82Illegal user access 83.It Dv DTRACEFLT_TUPOFLOW 84Tuple stack overflow 85.It Dv DTRACEFLT_BADSTACK 86Bad stack 87.El 88.Sh FILES 89.Bl -tag -width '<sys/dtrace.h>' 90.It In sys/dtrace.h 91The header file containing the definitions of DTrace fault types. 92.El 93.Sh EXAMPLES 94.Ss Example 1 : Custom Column Headers 95The following script uses the 96.Nm dtrace Ns Cm :::BEGIN 97probe to print column headers. 98Note the pragma line setting the 99.Ql quiet 100option to disable the default column headers. 101.Bd -literal -offset 2n 102#pragma D option quiet 103 104dtrace:::BEGIN 105{ 106 printf(" %12s %-20s %-20s %s\en", 107 "DELTA(us)", "OLD", "NEW", "TIMESTAMP"); 108} 109.Ed 110.Ss Example 2 : Handling Runtime Errors with dtrace:::ERROR 111The following script causes a runtime error by dereferencing a pointer 112on address 113.Ad 19930908 114in the 115.Cm BEGIN 116probe. 117As a result, the 118.Cm ERROR 119probe fires and prints out 120.Dq Oops 121along with the probe arguments. 122At that point, the program ends and fires the 123.Cm END 124probe. 125.\" It might look weird to define ERROR first, but that is on purpose. 126.\" This way the probe IDs and EPIDs are a bit more mixed up 127.\" and are easier to understand. 128.Bd -literal -offset 2n 129ERROR 130{ 131 printf("Oops\en"); 132 printf("EPID (arg1): %d\en", arg1); 133 printf("Action index (arg2): %d\en", arg2); 134 printf("DIF offset (arg3): %d\en", arg3); 135 printf("Fault type (arg4): %d\en", arg4); 136 printf("Accessed address (arg5): %X\en", arg5); 137 exit(1); 138} 139BEGIN 140{ 141 *(int *)0x19931101; 142} 143END { 144 printf("Bye"); 145} 146.Ed 147.Pp 148This script will result in the following output: 149.Bd -literal -offset 2n 150CPU ID FUNCTION:NAME 151 2 3 :ERROR Oops 152EPID (arg1): 2 153Action index (arg2): 1 154DIF offset (arg3): 16 155Fault type: 1 156arg5: 19931101 157 158dtrace: error on enabled probe ID 2 (ID 1: dtrace:::BEGIN): invalid address (0x19931101) in action #1 at DIF offset 16 159 2 2 :END Bye 160.Ed 161.Sh SEE ALSO 162.Xr dtrace 1 , 163.Xr tracing 7 164.Rs 165.%B The illumos Dynamic Tracing Guide 166.%O Chapter dtrace Provider 167.%D 2008 168.%U https://illumos.org/books/dtrace/chp-dtrace.html 169.Re 170.Sh AUTHORS 171This manual page was written by 172.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org . 173.Sh CAVEATS 174The 175.Nm dtrace Ns Cm :::ERROR 176probe arguments cannot be accessed through the typed 177.Va args[] 178array. 179.Pp 180.Xr dtrace 1 181will not fire the 182.Nm dtrace Ns Cm :::ERROR 183probe recursively. 184If an error occurs in one of the action statements of the 185.Nm dtrace Ns Cm :::ERROR , 186then 187.Xr dtrace 1 188will abort further processing of 189the 190.Nm dtrace Ns Cm :::ERROR 191probe's actions. 192