From nobody Mon Jul 14 12:18:46 2025 X-Original-To: dev-commits-src-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4bghF25Jhqz61gbg; Mon, 14 Jul 2025 12:18:46 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R10" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4bghF246Ysz3nGr; Mon, 14 Jul 2025 12:18:46 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1752495526; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=6VXKXHEN0hff3RvS5ysH43QjNwQFYL38tyKzrYW9fzE=; b=S21HkECvj9xgLPkGv86waaReAo3XB/NxvXUFdX7BK6NB0mxP1uN0vNtaCaS18BMmCBXRUb NtNmA4VCunf05oM68yYUajfwC43LRCp3pbmpyewNRvUqrRrkSaQ4R+COgD+rfV3q1XM5sa nGMGWsKqQ9FreW7jS59B/BZpW0TlrUAUAKywlRhpyo2vjxdmDLIK4t7AV3focxQUup4Ecl hsefxi4EFGZHHtwKGrf0AL9+qGKy/OFoHwvRqvjirZ3kyuAWrI+en0/4S4/gJq1SlZ+R21 7k2aSZ6R5zG094CKKwszqATcv2pgy2mjUHatElzugnTpwRIcelML5BbkhQqMAQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1752495526; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=6VXKXHEN0hff3RvS5ysH43QjNwQFYL38tyKzrYW9fzE=; b=thDdSy2PBpmQTA30gpcgtUcwyRaxwRr/AyiDt7A/SI8Z2qJgIFHe+Z0SZiQFlsjsnQiVFy Bw8QE0hB2aF6e2ko8t10ZjQZghpYE+lDzk3NVnUe9YZcgxIgwiysDBaGcLc6u+LU6d7+Rh sCtaCm/efqF6uGSrjS7yyGM/LkunxWQBdpk5owQP6YszJfxFjHB/27oRAUxdfiunHfRUdt URzI9CmNMg9edHGHYU4MkJYuzBbgiU6M3oOvcN60B/3IKxAqjcYBjze/S4I6dqOvw9sK2A 8qo3JUHGamMMQXs9cyjqZGz0660zz7p0JjjAJSUjAv5Bd9Kdf0nVya8TwabqhA== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1752495526; a=rsa-sha256; cv=none; b=IoqhtWw5cSqLximQZfOG4UZQyD5BajostRGaOaLDFLRW7TyA7q5XltWhlqU8GaNGX6GrgS 3KHKnnzA06TeOEplG8y9aueUnHmeh6o43awqVy/F7LEyQAhshK8zjzEx/vNv0npWlNKvwm egGCDgbn3i2v3sA0xVNARVHlT6HwrD2K+qK8XdD2YWAdw4cXZta29KiCb4pCoq8blTG2Jy eQF/f8E5yho4zvLU0xbCndPhWIZA0rrDPJxKbA2tL3DJGeFB4XhCIK2qbr1rgbHZcHF8MX LsP8xx1dkneaO1r9zdEf9jfuPX/MNjDQEOmfeSKKJOWt2xbvudW0/Y8y6OYzDQ== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4bghF23c4fztSM; Mon, 14 Jul 2025 12:18:46 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.18.1/8.18.1) with ESMTP id 56ECIk6q057041; Mon, 14 Jul 2025 12:18:46 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.18.1/8.18.1/Submit) id 56ECIkiV057038; Mon, 14 Jul 2025 12:18:46 GMT (envelope-from git) Date: Mon, 14 Jul 2025 12:18:46 GMT Message-Id: <202507141218.56ECIkiV057038@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Mateusz Piotrowski <0mp@FreeBSD.org> Subject: git: a487606afd9b - main - dtrace_dtrace.4: Document the DTrace dtrace provider List-Id: Commit messages for all branches of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-src-all@freebsd.org Sender: owner-dev-commits-src-all@FreeBSD.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: 0mp X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: a487606afd9b7c21d76fce29c43b53c7c7a3a8eb Auto-Submitted: auto-generated The branch main has been updated by 0mp: URL: https://cgit.FreeBSD.org/src/commit/?id=a487606afd9b7c21d76fce29c43b53c7c7a3a8eb commit a487606afd9b7c21d76fce29c43b53c7c7a3a8eb Author: Mateusz Piotrowski <0mp@FreeBSD.org> AuthorDate: 2025-07-11 20:28:26 +0000 Commit: Mateusz Piotrowski <0mp@FreeBSD.org> CommitDate: 2025-07-14 12:17:04 +0000 dtrace_dtrace.4: Document the DTrace dtrace provider Reviewed by: bcr, christos Event: Berlin Hackathon 202507 Relnotes: yes Differential Revision: https://reviews.freebsd.org/D51267 --- cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 | 1 + share/man/man4/Makefile | 1 + share/man/man4/dtrace_dtrace.4 | 191 +++++++++++++++++++++++++++ 3 files changed, 193 insertions(+) diff --git a/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 b/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 index 7a98baf39776..10a6922d79db 100644 --- a/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 +++ b/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 @@ -1223,6 +1223,7 @@ Invalid command line options or arguments were specified. .Xr cpp 1 , .Xr dwatch 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 index 7c8a8f3afc45..5648fd2c1a84 100644 --- a/share/man/man4/Makefile +++ b/share/man/man4/Makefile @@ -980,6 +980,7 @@ _ccd.4= ccd.4 .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 index 000000000000..b8c31005b47e --- /dev/null +++ b/share/man/man4/dtrace_dtrace.4 @@ -0,0 +1,191 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2025 Mateusz Piotrowski <0mp@FreeBSD.org> +.\" +.Dd July 14, 2025 +.Dt DTRACE_DTRACE 4 +.Os +.Sh NAME +.Nm dtrace_dtrace +.Nd a DTrace provider for BEGIN, END, and ERROR 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 has begun. +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 arg1 Ta Enabled probe identifier (EPID) +of the probe where the runtime error occurred +.It Fa arg2 Ta Index of the action statement that caused the error +.It Fa arg3 Ta DIF offset into the action if available (otherwise -1) +.It Fa arg4 Ta Fault type +.It Fa arg5 Ta Accessed address (or 0 if not applicable) when +.Va arg4 +is of fault type +.Dv DTRACEFLT_BADADDR , DTRACEFLT_BADALIGN , DTRACEFLT_KPRIV , +or +.Dv DTRACEFLT_UPRIV +.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\en", + "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 pointer +on address +.Ad 19930908 +in the +.Cm BEGIN +probe. +As a result, the +.Cm ERROR +probe fires and prints out +.Dq Oops +along with the probe arguments. +At that point, the program ends and fires the +.Cm END +probe. +.\" It might look weird to define ERROR first, but that is on purpose. +.\" This way the probe IDs and EPIDs are a bit more mixed up +.\" and are easier to understand. +.Bd -literal -offset 2n +ERROR +{ + printf("Oops\en"); + printf("EPID (arg1): %d\en", arg1); + printf("Action index (arg2): %d\en", arg2); + printf("DIF offset (arg3): %d\en", arg3); + printf("Fault type (arg4): %d\en", arg4); + printf("Accessed address (arg5): %X\en", arg5); + exit(1); +} +BEGIN +{ + *(int *)0x19931101; +} +END { + printf("Bye"); +} +.Ed +.Pp +This script will result in the following output: +.Bd -literal -offset 2n +CPU ID FUNCTION:NAME + 2 3 :ERROR Oops +EPID (arg1): 2 +Action index (arg2): 1 +DIF offset (arg3): 16 +Fault type: 1 +arg5: 19931101 + +dtrace: error on enabled probe ID 2 (ID 1: dtrace:::BEGIN): invalid address (0x19931101) in action #1 at DIF offset 16 + 2 2 :END Bye +.Ed +.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.