git: 13ac0282a8 - main - handbook/dtrace: Add references and refresh some paragraphs

Go to: [ bottom of page ] [ top of archives ] [ this month ]
From: Mateusz Piotrowski <0mp_at_FreeBSD.org>
Date: Thu, 17 Jul 2025 19:48:46 UTC
The branch main has been updated by 0mp:

URL: https://cgit.FreeBSD.org/doc/commit/?id=13ac0282a853954f15705906150ab6dd91f20ac2

commit 13ac0282a853954f15705906150ab6dd91f20ac2
Author:     Mateusz Piotrowski <0mp@FreeBSD.org>
AuthorDate: 2025-07-17 19:46:34 +0000
Commit:     Mateusz Piotrowski <0mp@FreeBSD.org>
CommitDate: 2025-07-17 19:48:41 +0000

    handbook/dtrace: Add references and refresh some paragraphs
    
    - Reference manual pages where appropriate
    - Rewrite some paragraphs for better clarity
    - Do some minor wordsmithing
    - Do not explain how ksh is needed for the DTrace Toolkit. That's what
      RUN_DEPENDS are for.
---
 .../content/en/books/handbook/dtrace/_index.adoc   | 32 ++++++++++------------
 1 file changed, 14 insertions(+), 18 deletions(-)

diff --git a/documentation/content/en/books/handbook/dtrace/_index.adoc b/documentation/content/en/books/handbook/dtrace/_index.adoc
index 26a50a890d..7e9dfc52f4 100644
--- a/documentation/content/en/books/handbook/dtrace/_index.adoc
+++ b/documentation/content/en/books/handbook/dtrace/_index.adoc
@@ -88,18 +88,18 @@ To load all of the necessary modules:
 # kldload dtraceall
 ....
 
-Beginning with FreeBSD 10.0-RELEASE, the modules are automatically loaded when `dtrace` is run.
+Beginning with FreeBSD 10.0-RELEASE, the modules are automatically loaded when man:dtrace[1] is run.
 
-FreeBSD uses the `DDB_CTF` kernel option to enable support for loading `CTF` data from kernel modules and the kernel itself.
-`CTF` is the Solaris(TM) Compact C Type Format which encapsulates a reduced form of debugging information similar to `DWARF` and the venerable stabs. 
-`CTF` data is added to binaries by the `ctfconvert` and `ctfmerge` build tools.
+FreeBSD uses the `DDB_CTF` kernel option to enable support for loading man:ctf[5] data from kernel modules and the kernel itself.
+`CTF` is the Solaris(TM) Compact C Type Format which encapsulates a reduced form of debugging information similar to `DWARF` and the venerable stabs.
+`CTF` data is added to binaries by the man:ctfconvert[1] and man:ctfmerge[1] build tools.
 The `ctfconvert` utility parses `DWARF``ELF` debug sections created by the compiler and `ctfmerge` merges `CTF``ELF` sections from objects into either executables or shared libraries.
 
 Some different providers exist for FreeBSD than for Solaris(TM).
-Most notable is the `dtmalloc` provider, which allows tracing `malloc()` by type in the FreeBSD kernel.
+Most notable is the `dtmalloc` provider, which allows tracing man:malloc[9] by type in the FreeBSD kernel.
 Some of the providers found in Solaris(TM), such as `cpc` and `mib`, are not present in FreeBSD.
 These may appear in future versions of FreeBSD.
-Moreover, some of the providers available in both operating systems are not compatible, in the sense that their probes have different argument types. 
+Moreover, some of the providers available in both operating systems are not compatible, in the sense that their probes have different argument types.
 Thus, `D` scripts written on Solaris(TM) may or may not work unmodified on FreeBSD, and vice versa.
 
 Due to security differences, only `root` may use DTrace on FreeBSD.
@@ -131,17 +131,12 @@ Users of the AMD64 architecture should also add this line:
 options         KDTRACE_FRAME
 ....
 
-This option provides support for `FBT`.
+This option provides support for man:dtrace_fbt[4].
 While DTrace will work without this option, there will be limited support for function boundary tracing.
 
-Once the FreeBSD system has rebooted into the new kernel, or the DTrace kernel modules have been loaded using `kldload dtraceall`, the system will need support for the Korn shell as the DTrace Toolkit has several utilities written in `ksh`.
-Make sure that the package:shells/ksh93[] package or port is installed.
-It is also possible to run these tools under package:shells/pdksh[] or package:shells/mksh[].
-
-Finally, install the current DTrace Toolkit, a collection of ready-made scripts for collecting system information.
-There are scripts to check open files, memory, `CPU` usage, and a lot more.
-FreeBSD 10 installs a few of these scripts into [.filename]#/usr/share/dtrace#.
-On other FreeBSD versions, or to install the full DTrace Toolkit, use the package:sysutils/dtrace-toolkit[] package or port.
+Once the FreeBSD system has rebooted into the new kernel, or the DTrace kernel modules have been loaded using `kldload dtraceall`, install the current DTrace Toolkit (package:sysutils/dtrace-toolkit[]), a collection of ready-made scripts for collecting system information.
+There are scripts to check open files, memory, CPU usage, and a lot more.
+FreeBSD includes some scripts in the base system as well; see [.filename]#/usr/share/dtrace#.
 
 [NOTE]
 ====
@@ -152,7 +147,8 @@ Not all of the scripts found in the DTrace Toolkit will work as-is on FreeBSD an
 The DTrace Toolkit includes many scripts in the special language of DTrace.
 This language is called the D language and it is very similar to C++.
 An in depth discussion of the language is beyond the scope of this document.
-It is covered extensively in the https://www.illumos.org/books/dtrace/bookinfo.html[illumos Dynamic Tracing Guide].
+Refer to the FreeBSD man:d[7] manual page for an overview of the D language on FreeBSD.
+The D language is also covered extensively in the https://www.illumos.org/books/dtrace/bookinfo.html[illumos Dynamic Tracing Guide].
 
 [[dtrace-out-of-kernel]]
 == Enabling DTrace in Out-of-Kernel Modules
@@ -183,7 +179,7 @@ To view all probes, the administrator can execute the following command:
 # dtrace -l | more
 ....
 
-Each probe has an `ID`, a `PROVIDER` (dtrace or fbt), a `MODULE`, and a `FUNCTION NAME`.
+Each probe has an `ID`, a `PROVIDER` (e.g., `dtrace` or `fbt`), a `MODULE`, and a `FUNCTION NAME`.
 Refer to man:dtrace[1] for more information about this command.
 
 The examples in this section provide an overview of how to use two of the fully supported scripts from the DTrace Toolkit: the [.filename]#hotkernel# and [.filename]#procsystime# scripts.
@@ -288,4 +284,4 @@ Elapsed Times for processes csh,
             read         3988049784
 ....
 
-As shown, the `read()` system call used the most time in nanoseconds while the `getpid()` system call used the least amount of time.
+As shown, the man:read[2] system call used the most time in nanoseconds while the man:getpid[2] system call used the least amount of time.