diff options
Diffstat (limited to 'static/freebsd/man4/dtrace_dtrace.4 3.html')
| -rw-r--r-- | static/freebsd/man4/dtrace_dtrace.4 3.html | 228 |
1 files changed, 228 insertions, 0 deletions
diff --git a/static/freebsd/man4/dtrace_dtrace.4 3.html b/static/freebsd/man4/dtrace_dtrace.4 3.html new file mode 100644 index 00000000..f8097489 --- /dev/null +++ b/static/freebsd/man4/dtrace_dtrace.4 3.html @@ -0,0 +1,228 @@ +<table class="head"> + <tr> + <td class="head-ltitle">DTRACE_DTRACE(4)</td> + <td class="head-vol">Device Drivers Manual</td> + <td class="head-rtitle">DTRACE_DTRACE(4)</td> + </tr> +</table> +<div class="manual-text"> +<section class="Sh"> +<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> +<p class="Pp"><code class="Nm">dtrace_dtrace</code> — <span class="Nd">a + DTrace provider for BEGIN, END, and ERROR probes</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<table class="Nm"> + <tr> + <td><code class="Nm">dtrace<code class="Cm">:::BEGIN</code></code></td> + <td></td> + </tr> +</table> +<br/> +<table class="Nm"> + <tr> + <td><code class="Nm">dtrace<code class="Cm">:::END</code></code></td> + <td></td> + </tr> +</table> +<br/> +<table class="Nm"> + <tr> + <td><code class="Nm">dtrace<code class="Cm">:::ERROR</code></code></td> + <td></td> + </tr> +</table> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The <code class="Nm">dtrace</code> provider implements three + special probes related to the life cycle of the DTrace program itself.</p> +<section class="Ss"> +<h2 class="Ss" id="dtrace:::BEGIN"><a class="permalink" href="#dtrace:::BEGIN">dtrace:::BEGIN</a></h2> +<p class="Pp">The <code class="Nm">dtrace</code><code class="Cm">:::BEGIN</code> + probe fires at the beginning of a <a class="Xr">dtrace(1)</a>, program + before tracing has begun. It provides a convenient place for initializing + variables and printing column headers.</p> +<p class="Pp">Variables such as <var class="Va">stack</var> or + <var class="Va">execname</var> cannot be relied upon in the execution + context of the + <code class="Nm">dtrace</code><code class="Cm">:::BEGIN</code> probe.</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="dtrace:::END"><a class="permalink" href="#dtrace:::END">dtrace:::END</a></h2> +<p class="Pp">The <code class="Nm">dtrace</code><code class="Cm">:::END</code> + probe fires at the end of a <a class="Xr">dtrace(1)</a> program, when all + tracing has stopped.</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="dtrace:::ERROR"><a class="permalink" href="#dtrace:::ERROR">dtrace:::ERROR</a></h2> +<p class="Pp">The <code class="Nm">dtrace</code><code class="Cm">:::ERROR</code> + probe fires when an unexpected runtime error occurs in another probe.</p> +<p class="Pp">The following table describes the arguments to + <code class="Nm">dtrace</code><code class="Cm">:::ERROR</code>.</p> +<table class="Bl-column Bd-indent"> + <tr id="Argument"> + <td><a class="permalink" href="#Argument"><b class="Sy">Argument</b></a></td> + <td><a class="permalink" href="#Definition"><b class="Sy" id="Definition">Definition</b></a></td> + </tr> + <tr> + <td><var class="Fa">arg1</var></td> + <td>Enabled probe identifier (EPID) of the probe where the runtime error + occurred</td> + </tr> + <tr> + <td><var class="Fa">arg2</var></td> + <td>Index of the action statement that caused the error</td> + </tr> + <tr> + <td><var class="Fa">arg3</var></td> + <td>DIF offset into the action if available (otherwise -1)</td> + </tr> + <tr> + <td><var class="Fa">arg4</var></td> + <td>Fault type</td> + </tr> + <tr> + <td><var class="Fa">arg5</var></td> + <td>Accessed address (or 0 if not applicable) when + <var class="Va">arg4</var> is of fault type + <code class="Dv">DTRACEFLT_BADADDR</code>, + <code class="Dv">DTRACEFLT_BADALIGN</code>, + <code class="Dv">DTRACEFLT_KPRIV</code>, or + <code class="Dv">DTRACEFLT_UPRIV</code></td> + </tr> +</table> +<p class="Pp">The fault types are:</p> +<div class="Bd-indent"> +<dl class="Bl-tag Bl-compact"> + <dt id="DTRACEFLT_UNKNOWN"><a class="permalink" href="#DTRACEFLT_UNKNOWN"><code class="Dv">DTRACEFLT_UNKNOWN</code></a></dt> + <dd>Unknown fault</dd> + <dt id="DTRACEFLT_BADADDR"><a class="permalink" href="#DTRACEFLT_BADADDR"><code class="Dv">DTRACEFLT_BADADDR</code></a></dt> + <dd>Bad address</dd> + <dt id="DTRACEFLT_BADALIGN"><a class="permalink" href="#DTRACEFLT_BADALIGN"><code class="Dv">DTRACEFLT_BADALIGN</code></a></dt> + <dd>Bad alignment</dd> + <dt id="DTRACEFLT_ILLOP"><a class="permalink" href="#DTRACEFLT_ILLOP"><code class="Dv">DTRACEFLT_ILLOP</code></a></dt> + <dd>Illegal operation</dd> + <dt id="DTRACEFLT_DIVZERO"><a class="permalink" href="#DTRACEFLT_DIVZERO"><code class="Dv">DTRACEFLT_DIVZERO</code></a></dt> + <dd>Divide-by-zero</dd> + <dt id="DTRACEFLT_NOSCRATCH"><a class="permalink" href="#DTRACEFLT_NOSCRATCH"><code class="Dv">DTRACEFLT_NOSCRATCH</code></a></dt> + <dd>Out of scratch space</dd> + <dt id="DTRACEFLT_KPRIV"><a class="permalink" href="#DTRACEFLT_KPRIV"><code class="Dv">DTRACEFLT_KPRIV</code></a></dt> + <dd>Illegal kernel access</dd> + <dt id="DTRACEFLT_UPRIV"><a class="permalink" href="#DTRACEFLT_UPRIV"><code class="Dv">DTRACEFLT_UPRIV</code></a></dt> + <dd>Illegal user access</dd> + <dt id="DTRACEFLT_TUPOFLOW"><a class="permalink" href="#DTRACEFLT_TUPOFLOW"><code class="Dv">DTRACEFLT_TUPOFLOW</code></a></dt> + <dd>Tuple stack overflow</dd> + <dt id="DTRACEFLT_BADSTACK"><a class="permalink" href="#DTRACEFLT_BADSTACK"><code class="Dv">DTRACEFLT_BADSTACK</code></a></dt> + <dd>Bad stack</dd> +</dl> +</div> +</section> +</section> +<section class="Sh"> +<h1 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h1> +<dl class="Bl-tag"> + <dt><code class="In"><<a class="In">sys/dtrace.h</a>></code></dt> + <dd>The header file containing the definitions of DTrace fault types.</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> +<section class="Ss"> +<h2 class="Ss" id="Example_1_:_Custom_Column_Headers"><a class="permalink" href="#Example_1_:_Custom_Column_Headers">Example + 1: Custom Column Headers</a></h2> +<p class="Pp">The following script uses the + <code class="Nm">dtrace</code><code class="Cm">:::BEGIN</code> probe to + print column headers. Note the pragma line setting the + ‘<code class="Li">quiet</code>’ option to disable the default + column headers.</p> +<div class="Bd Pp Bd-indent Li"> +<pre>#pragma D option quiet + +dtrace:::BEGIN +{ + printf(" %12s %-20s %-20s %s\n", + "DELTA(us)", "OLD", "NEW", "TIMESTAMP"); +}</pre> +</div> +</section> +<section class="Ss"> +<h2 class="Ss" id="Example_2_:_Handling_Runtime_Errors_with_dtrace:::ERROR"><a class="permalink" href="#Example_2_:_Handling_Runtime_Errors_with_dtrace:::ERROR">Example + 2: Handling Runtime Errors with dtrace:::ERROR</a></h2> +<p class="Pp">The following script causes a runtime error by dereferencing a + pointer on address <span class="Ad">19930908</span> in the + <code class="Cm">BEGIN</code> probe. As a result, the + <code class="Cm">ERROR</code> probe fires and prints out + “Oops” along with the probe arguments. At that point, the + program ends and fires the <code class="Cm">END</code> probe.</p> +<div class="Bd Pp Bd-indent Li"> +<pre>ERROR +{ + printf("Oops\n"); + printf("EPID (arg1): %d\n", arg1); + printf("Action index (arg2): %d\n", arg2); + printf("DIF offset (arg3): %d\n", arg3); + printf("Fault type (arg4): %d\n", arg4); + printf("Accessed address (arg5): %X\n", arg5); + exit(1); +} +BEGIN +{ + *(int *)0x19931101; +} +END { + printf("Bye"); +}</pre> +</div> +<p class="Pp">This script will result in the following output:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>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</pre> +</div> +</section> +</section> +<section class="Sh"> +<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<p class="Pp"><a class="Xr">dtrace(1)</a>, <a class="Xr">tracing(7)</a></p> +<p class="Pp"><cite class="Rs"><i class="RsB">The illumos Dynamic Tracing + Guide</i>, + <a class="RsU" href="https://illumos.org/books/dtrace/chp-dtrace.html">https://illumos.org/books/dtrace/chp-dtrace.html</a>, + <span class="RsD">2008</span>, <span class="RsO">Chapter dtrace + Provider</span>.</cite></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp">This manual page was written by <span class="An">Mateusz + Piotrowski</span> + <<a class="Mt" href="mailto:0mp@FreeBSD.org">0mp@FreeBSD.org</a>>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="CAVEATS"><a class="permalink" href="#CAVEATS">CAVEATS</a></h1> +<p class="Pp">The <code class="Nm">dtrace</code><code class="Cm">:::ERROR</code> + probe arguments cannot be accessed through the typed + <var class="Va">args[]</var> array.</p> +<p class="Pp"><a class="Xr">dtrace(1)</a> will not fire the + <code class="Nm">dtrace</code><code class="Cm">:::ERROR</code> probe + recursively. If an error occurs in one of the action statements of the + <code class="Nm">dtrace</code><code class="Cm">:::ERROR</code>, then + <a class="Xr">dtrace(1)</a> will abort further processing of the + <code class="Nm">dtrace</code><code class="Cm">:::ERROR</code> probe's + actions.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">July 14, 2025</td> + <td class="foot-os">FreeBSD 15.0</td> + </tr> +</table> |