diff --git a/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 b/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 --- a/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 +++ b/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 @@ -1222,6 +1222,7 @@ .Sh SEE ALSO .Xr cpp 1 , .Xr dtrace_audit 4 , +.Xr dtrace_dtrace 4 , .Xr dtrace_io 4 , .Xr dtrace_ip 4 , .Xr dtrace_kinst 4 , diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile --- a/share/man/man4/Makefile +++ b/share/man/man4/Makefile @@ -980,6 +980,7 @@ .if ${MK_CDDL} != "no" _dtrace_provs= dtrace_audit.4 \ + dtrace_dtrace.4 \ dtrace_io.4 \ dtrace_ip.4 \ dtrace_kinst.4 \ diff --git a/share/man/man4/dtrace_dtrace.4 b/share/man/man4/dtrace_dtrace.4 new file mode 100644 --- /dev/null +++ b/share/man/man4/dtrace_dtrace.4 @@ -0,0 +1,196 @@ +.\" Copyright (c) 2025 Mateusz Piotrowski <0mp@FreeBSD.org> +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" 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 +.\" SUCH DAMAGE. +.\" +.Dd July 11, 2025 +.Dt DTRACE_DTRACE 4 +.Os +.Sh NAME +.Nm dtrace_dtrace +.Nd a DTrace provider for DTrace-related probes +.Sh SYNOPSIS +.Nm dtrace Ns Cm :::BEGIN +.Nm dtrace Ns Cm :::END +.Nm dtrace Ns Cm :::ERROR +.Sh DESCRIPTION +The +.Nm dtrace +provider implements three special probes related to the life cycle of the +DTrace program itself. +.Ss dtrace:::BEGIN +The +.Nm dtrace Ns Cm :::BEGIN +probe fires at the beginning of a +.Xr dtrace 1 +program before tracing begins. +It provides a convenient place for initializing variables +and printing column headers. +.Pp +Variables such as +.Va stack +or +.Va execname +cannot be relied upon in the execution context of the +.Nm dtrace Ns Cm :::BEGIN +probe. +.Ss dtrace:::END +The +.Nm dtrace Ns Cm :::END +probe fires at the end of a +.Xr dtrace 1 +program when all tracing has stopped. +.Ss dtrace:::ERROR +The +.Nm dtrace Ns Cm :::ERROR +probe fires when an unexpected runtime error occurs in another probe. +.Pp +The following table describes the arguments to +.Nm dtrace Ns Cm :::ERROR . +.Bl -column -offset indent "Argument" "Definition" +.It Sy Argument Ta Sy Definition +.It Fa arg0 Ta The enabled probe identifier (EPID) +of the probe where the runtime error occurred +.It Fa arg1 Ta The index of the action statement that caused the error +.It Fa arg2 Ta The DIF offset into the action if available (-1 otherwise) +.It Fa arg3 Ta The fault type +.It Fa arg4 Ta The accessed address in case of +.Dv DTRACEFLT_BADADDR , DTRACEFLT_BADALIGN , DTRACEFLT_KPRIV , +and +.Dv DTRACEFLT_UPRIV +or 0 if not applicable +.El +.Pp +The fault types are: +.Bl -tag -offset indent -width "DTRACEFLT_NOSCRATCH" -compact +.It Dv DTRACEFLT_UNKNOWN +Unknown fault +.It Dv DTRACEFLT_BADADDR +Bad address +.It Dv DTRACEFLT_BADALIGN +Bad alignment +.It Dv DTRACEFLT_ILLOP +Illegal operation +.It Dv DTRACEFLT_DIVZERO +Divide-by-zero +.It Dv DTRACEFLT_NOSCRATCH +Out of scratch space +.It Dv DTRACEFLT_KPRIV +Illegal kernel access +.It Dv DTRACEFLT_UPRIV +Illegal user access +.It Dv DTRACEFLT_TUPOFLOW +Tuple stack overflow +.It Dv DTRACEFLT_BADSTACK +Bad stack +.El +.Sh FILES +.Bl -tag -width '' +.It In sys/dtrace.h +The header file containing the definitions of DTrace fault types. +.El +.Sh EXAMPLES +.Ss Example 1 : Custom Column Headers +The following script uses the +.Nm dtrace Ns Cm :::BEGIN +probe to print column headers. +Note the pragma line setting the +.Ql quiet +option to disable the default column headers. +.Bd -literal -offset 2n +#pragma D option quiet + +dtrace:::BEGIN +{ + printf(" %12s %-20s %-20s %s\\n", + "DELTA(us)", "OLD", "NEW", "TIMESTAMP"); +} +.Ed +.Ss Example 2 : Handling Runtime Errors with dtrace:::ERROR +The following script causes a runtime error by dereferencing a null pointer +in the +.Cm BEGIN +probe. +As a result, the +.Cm ERROR +probe fires, prints out +.Dq Oops , +and calls +.Fn exit . +At that point the program ends and fires the +.Cm END +probe. +.Bd -literal -offset 2n +ERROR { + printf("Oops"); + exit(1); +} +BEGIN { + *(int *)NULL; +} +END { + printf("Bye"); +} +.Ed +.Pp +This script will result in the following output: +.Bd -literal -offset 2n +CPU ID FUNCTION:NAME + 6 3 :ERROR Oops +dtrace: error on enabled probe ID 2 (ID 1: dtrace:::BEGIN): invalid address (0x0) in action #1 at DIF offset 16 + 6 2 :END Bye +.Ed +.Pp +Notice that the error message already includes all details provided +to the +.Nm dtrace Ns Cm :::ERROR +probe via probe arguments. +.Sh SEE ALSO +.Xr dtrace 1 , +.Xr tracing 7 +.Rs +.%B The illumos Dynamic Tracing Guide +.%O Chapter dtrace Provider +.%D 2008 +.%U https://illumos.org/books/dtrace/chp-dtrace.html +.Re +.Sh AUTHORS +This manual page was written by +.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org . +.Sh CAVEATS +The +.Nm dtrace Ns Cm :::ERROR +probe arguments cannot be accessed through the typed +.Va args[] +array. +.Pp +.Xr dtrace 1 +will not fire the +.Nm dtrace Ns Cm :::ERROR +probe recursively. +If an error occurs in one of the action statements of the +.Nm dtrace Ns Cm :::ERROR , +then +.Xr dtrace 1 +will abort further processing of +the +.Nm dtrace Ns Cm :::ERROR +probe's actions.