Page MenuHomeFreeBSD
Files F154718177

D51267.id158360.diff
No OneTemporary
Actions

D51267.id158360.diff
View Options

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,178 @@
+.\"
+.\" SPDX-License-Identifier: BSD-2-Clause
+.\"
+.\" Copyright (c) 2025 Mateusz Piotrowski <0mp@FreeBSD.org>
+.\"
+.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 '<sys/dtrace.h>'
+.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.

File Metadata

Mime Type
text/plain
Expires
Thu, Apr 30, 7:25 AM (20 h, 35 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
32469690
Default Alt Text
D51267.id158360.diff (5 KB)

Event Timeline