diff options
Diffstat (limited to 'static/freebsd/man7/d.7 3.html')
| -rw-r--r-- | static/freebsd/man7/d.7 3.html | 377 |
1 files changed, 377 insertions, 0 deletions
diff --git a/static/freebsd/man7/d.7 3.html b/static/freebsd/man7/d.7 3.html new file mode 100644 index 00000000..c0b17698 --- /dev/null +++ b/static/freebsd/man7/d.7 3.html @@ -0,0 +1,377 @@ +<table class="head"> + <tr> + <td class="head-ltitle">D(7)</td> + <td class="head-vol">Miscellaneous Information Manual</td> + <td class="head-rtitle">D(7)</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">D</code> — <span class="Nd">DTrace + scripting language overview</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<p class="Pp"><var class="Ar">provider</var><code class="Cm">:</code><var class="Ar">module</var><code class="Cm">:</code><var class="Ar">function</var><code class="Cm">:</code><var class="Ar">name</var> + [[<code class="Cm">/</code><var class="Ar">predicate</var><code class="Cm">/</code>] + <code class="Cm">{</code><var class="Ar">action</var><code class="Cm">}</code>]</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp"><code class="Nm">D</code> is the <a class="Xr">dtrace(1)</a> + scripting language. This manual provides a brief reference of the + <code class="Nm">D</code> language and scripting.</p> +<p class="Pp">This manual page serves as a short reference of the language. + Refer to books listed in <a class="Sx" href="#SEE_ALSO">SEE ALSO</a> for a + complete reference.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="PROBE'S_DESCRIPTION"><a class="permalink" href="#PROBE'S_DESCRIPTION">PROBE'S + DESCRIPTION</a></h1> +<p class="Pp">A probe's description consists of four elements:</p> +<div class="Bd + Bd-indent"><var class="Ar">provider</var><code class="Cm">:</code><var class="Ar">module</var><code class="Cm">:</code><var class="Ar">function</var><code class="Cm">:</code><var class="Ar">name</var></div> +<p class="Pp">The exact meaning of <var class="Ar">module</var>, + <var class="Ar">function</var>, and <var class="Ar">name</var> depends on + <var class="Ar">provider</var>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="USER-DEFINED_VARIABLE_TYPES"><a class="permalink" href="#USER-DEFINED_VARIABLE_TYPES">USER-DEFINED + VARIABLE TYPES</a></h1> +<table class="Bl-column"> + <tr id="Type"> + <td><a class="permalink" href="#Type"><b class="Sy">Type</b></a></td> + <td><a class="permalink" href="#Syntax"><b class="Sy" id="Syntax">Syntax</b></a></td> + </tr> + <tr id="variable_name"> + <td>global</td> + <td><var class="Va">variable_name</var></td> + </tr> + <tr id="@"> + <td>aggregate</td> + <td><a class="permalink" href="#@"><b class="Sy">@</b></a><var class="Va">variable_name</var></td> + </tr> + <tr id="self-_"> + <td>thread-local</td> + <td><a class="permalink" href="#self-_"><b class="Sy">self-></b></a><var class="Va">variable_name</var></td> + </tr> + <tr id="this-_"> + <td>clause-local</td> + <td><a class="permalink" href="#this-_"><b class="Sy">this-></b></a><var class="Va">variable_name</var></td> + </tr> +</table> +<p class="Pp" id="Tips"><a class="permalink" href="#Tips"><i class="Em">Tips</i></a>:</p> +<ul class="Bl-dash Bl-compact"> + <li>Always use the variable type with the smallest scope to minimize + processing overhead.</li> + <li>Use aggregate variables instead of global variables when possible. + Aggregate variables are multi-CPU safe in contrast to global + variables.</li> +</ul> +</section> +<section class="Sh"> +<h1 class="Sh" id="BUILT-IN_VARIABLES"><a class="permalink" href="#BUILT-IN_VARIABLES">BUILT-IN + VARIABLES</a></h1> +<section class="Ss"> +<h2 class="Ss" id="Probe_Arguments"><a class="permalink" href="#Probe_Arguments">Probe + Arguments</a></h2> +<dl class="Bl-tag"> + <dt id="args__"><var class="Va">args[]</var></dt> + <dd>The array of typed probe arguments.</dd> + <dt id="arg0"><var class="Va">arg0</var>, <var class="Va">...</var>, + <var class="Va">arg9</var></dt> + <dd>The untyped probe arguments represented as 64-bit unsigned integers. Only + the first ten arguments are available this way.</dd> +</dl> +</section> +<section class="Ss"> +<h2 class="Ss" id="Probe_Information"><a class="permalink" href="#Probe_Information">Probe + Information</a></h2> +<dl class="Bl-tag"> + <dt id="epid"><var class="Va">epid</var></dt> + <dd>The enabled probe ID which uniquely identifies an enabled probe. An + enabled probe is defined by its probe ID, its predicates, and its + actions.</dd> + <dt id="id"><var class="Va">id</var></dt> + <dd>The probe ID which uniquely identifies a probe available to DTrace.</dd> + <dt id="probeprov"><var class="Va">probeprov</var></dt> + <dd>The <var class="Ar">provider</var> in the probe's description + (<var class="Ar">provider</var><code class="Cm">:</code><var class="Ar">module</var><code class="Cm">:</code><var class="Ar">function</var><code class="Cm">:</code><var class="Ar">name</var>).</dd> + <dt id="probemod"><var class="Va">probemod</var></dt> + <dd>The <var class="Ar">module</var> in the probe's description + (<var class="Ar">provider</var><code class="Cm">:</code><var class="Ar">module</var><code class="Cm">:</code><var class="Ar">function</var><code class="Cm">:</code><var class="Ar">name</var>).</dd> + <dt id="probefunc"><var class="Va">probefunc</var></dt> + <dd>The <var class="Ar">function</var> in the probe's description + (<var class="Ar">provider</var><code class="Cm">:</code><var class="Ar">module</var><code class="Cm">:</code><var class="Ar">function</var><code class="Cm">:</code><var class="Ar">name</var>).</dd> + <dt id="probename"><var class="Va">probename</var></dt> + <dd>The <var class="Ar">name</var> in the probe's description + (<var class="Ar">provider</var><code class="Cm">:</code><var class="Ar">module</var><code class="Cm">:</code><var class="Ar">function</var><code class="Cm">:</code><var class="Ar">name</var>).</dd> +</dl> +</section> +<section class="Ss"> +<h2 class="Ss" id="Process_Information"><a class="permalink" href="#Process_Information">Process + Information</a></h2> +<dl class="Bl-tag"> + <dt id="execargs"><var class="Va">execargs</var></dt> + <dd>The process arguments. Effectively, + ‘<code class="Li">curthread->td_proc->p_args</code>’.</dd> + <dt id="execname"><var class="Va">execname</var></dt> + <dd>The name of the current process. Effectively, + ‘<code class="Li">curthread->td_proc->p_comm</code>’.</dd> + <dt id="gid"><var class="Va">gid</var></dt> + <dd>The group ID of the current process.</dd> + <dt id="pid"><var class="Va">pid</var></dt> + <dd>The process ID of the current process.</dd> + <dt id="ppid"><var class="Va">ppid</var></dt> + <dd>The parent process ID of the current process.</dd> + <dt id="uid"><var class="Va">uid</var></dt> + <dd>The user ID of the current process.</dd> +</dl> +</section> +<section class="Ss"> +<h2 class="Ss" id="Thread_Information"><a class="permalink" href="#Thread_Information">Thread + Information</a></h2> +<dl class="Bl-tag"> + <dt id="uregs__"><var class="Va">uregs[]</var></dt> + <dd>The saved user-mode register values.</dd> + <dt id="cpu"><var class="Va">cpu</var></dt> + <dd>The ID of the current CPU.</dd> + <dt id="stackdepth"><var class="Va">stackdepth</var></dt> + <dd>The kernel stack frame depth.</dd> + <dt id="ustackdepth"><var class="Va">ustackdepth</var></dt> + <dd>The userspace counterpart of <var class="Va">stackdepth</var>.</dd> + <dt id="tid"><var class="Va">tid</var></dt> + <dd>The thread ID. Depending on the context, this can be either the ID of a + kernel thread or a thread in a user process.</dd> + <dt id="errno"><var class="Va">errno</var></dt> + <dd>The <a class="Xr">errno(2)</a> value of the last system call performed by + the current thread.</dd> + <dt id="curlwpsinfo"><var class="Va">curlwpsinfo</var></dt> + <dd>A pointer to the <var class="Vt">lwpsinfo_t</var> representation of the + current thread. Refer to <a class="Xr">dtrace_proc(4)</a> for more + details.</dd> + <dt id="curpsinfo"><var class="Va">curpsinfo</var></dt> + <dd>A pointer to the <var class="Vt">psinfo_t</var> representation of the + current process. Refer to <a class="Xr">dtrace_proc(4)</a> for more + details.</dd> + <dt id="curthread"><var class="Va">curthread</var></dt> + <dd>A pointer to the thread struct that is currently on-CPU. E.g., + ‘<code class="Li">curthread->td_name</code>’ returns the + thread name. The + <code class="In"><<a class="In">sys/proc.h</a>></code> header + documents all members of <var class="Vt">struct thread</var>.</dd> + <dt id="caller"><var class="Va">caller</var></dt> + <dd>The address of the kernel thread instruction at the time of execution of + the current probe.</dd> + <dt id="ucaller"><var class="Va">ucaller</var></dt> + <dd>The userspace counterpart of <var class="Va">caller</var>.</dd> +</dl> +</section> +<section class="Ss"> +<h2 class="Ss" id="Timestamps"><a class="permalink" href="#Timestamps">Timestamps</a></h2> +<dl class="Bl-tag"> + <dt id="timestamp"><var class="Va">timestamp</var></dt> + <dd>The number of nanoseconds since boot. Suitable for calculating relative + time differences of elapsed time and latency.</dd> + <dt id="vtimestamp"><var class="Va">vtimestamp</var></dt> + <dd>The number of nanoseconds that the current thread spent on CPU. The + counter is not increased during handling of a fired DTrace probe. Suitable + for calculating relative time differences of on-CPU time.</dd> + <dt id="walltimestamp"><var class="Va">walltimestamp</var></dt> + <dd>The number of nanoseconds since the Epoch (1970-01-01T00+00:00). Suitable + for timestamping logs.</dd> +</dl> +</section> +</section> +<section class="Sh"> +<h1 class="Sh" id="BUILT-IN_FUNCTIONS"><a class="permalink" href="#BUILT-IN_FUNCTIONS">BUILT-IN + FUNCTIONS</a></h1> +<dl class="Bl-tag"> + <dt id="strchr"><var class="Ft">string</var> + <a class="permalink" href="#strchr"><code class="Fn">strchr</code></a>(<var class="Fa">string + s</var>, <var class="Fa">char c</var>)</dt> + <dd>Return a substring of <var class="Fa">s</var> starting at the first + occurance of <var class="Fa">c</var> in <var class="Fa">s</var>. Return + <code class="Dv">NULL</code> if <var class="Fa">c</var> does not occur in + <var class="Fa">s</var>. + <p class="Pp">For example,</p> + <div class="Bd Bd-indent Li"> + <pre>strchr("abc", 'b');</pre> + </div> + returns ‘<code class="Li">bc</code>’ and + <div class="Bd Bd-indent Li"> + <pre>strchr("abc", 'd');</pre> + </div> + returns <code class="Dv">NULL</code>.</dd> + <dt id="strjoin"><var class="Ft">string</var> + <a class="permalink" href="#strjoin"><code class="Fn">strjoin</code></a>(<var class="Fa">string + s1</var>, <var class="Fa">string s2</var>)</dt> + <dd>Return a string resulting from concatenating <var class="Fa">s1</var> and + <var class="Fa">s2</var>. + <p class="Pp">For example,</p> + <div class="Bd Bd-indent Li"> + <pre>strjoin("abc", "def")</pre> + </div> + returns ‘<code class="Li">abcdef</code>’.</dd> + <dt id="strrchr"><var class="Ft">string</var> + <a class="permalink" href="#strrchr"><code class="Fn">strrchr</code></a>(<var class="Fa">string + s</var>, <var class="Fa">char c</var>)</dt> + <dd>Return a substring of <var class="Fa">s</var> starting at the last + occurance of <var class="Fa">c</var> in <var class="Fa">s</var>. Similar + to <code class="Fn">strchr</code>().</dd> + <dt id="strstr"><var class="Ft">string</var> + <a class="permalink" href="#strstr"><code class="Fn">strstr</code></a>(<var class="Fa">string + haystack</var>, <var class="Fa">string needle</var>)</dt> + <dd>Return a substring of <var class="Fa">haystack</var> starting at the first + occurrence of <var class="Fa">needle</var>. Return + <code class="Dv">NULL</code> if <var class="Fa">needle</var> is not a + substring of <var class="Fa">haystack</var>. + <p class="Pp">For example,</p> + <div class="Bd Bd-indent Li"> + <pre>strstr("abc1bc2", "bc")</pre> + </div> + returns ‘<code class="Li">bc1bc2</code>’ and + <div class="Bd Bd-indent Li"> + <pre>strstr("abc", "xy")</pre> + </div> + returns <code class="Dv">NULL</code>.</dd> + <dt id="strtok"><var class="Ft">string</var> + <a class="permalink" href="#strtok"><code class="Fn">strtok</code></a>(<var class="Fa">string + s</var>, <var class="Fa">string separators</var>)</dt> + <dd>Tokenize <var class="Fa">s</var> with <var class="Fa">separators</var>. + <p class="Pp">For example,</p> + <div class="Bd Bd-indent Li"> + <pre>strtok("abcdefg", "xyzd")</pre> + </div> + returns ‘<code class="Li">abc</code>’.</dd> + <dt id="strlen"><var class="Ft">size_t</var> + <a class="permalink" href="#strlen"><code class="Fn">strlen</code></a>(<var class="Fa">string + s</var>)</dt> + <dd>Return the length of string <var class="Fa">s</var>.</dd> + <dt id="substr"><var class="Ft">string</var> + <a class="permalink" href="#substr"><code class="Fn">substr</code></a>(<var class="Fa">string + s</var>, <var class="Fa">int position</var>, <var class="Fa">[int + length]</var>)</dt> + <dd>Return a substring of string <var class="Fa">s</var> starting at + <var class="Fa">position</var>. The substring will be at most + <var class="Fa">length</var>-long. If <var class="Fa">length</var> is not + specified, use the rest of the string. If <var class="Fa">position</var> + is greater than the size of <var class="Fa">s</var>, return an empty + string. + <p class="Pp">For example,</p> + <div class="Bd Bd-indent Li"> + <pre>substr("abcd", 2)</pre> + </div> + returns ‘<code class="Li">cd</code>’, + <div class="Bd Bd-indent Li"> + <pre>substr("abcd", 2, 1)</pre> + </div> + returns ‘<code class="Li">c</code>’, and + <div class="Bd Bd-indent Li"> + <pre>substr("abcd", 99)</pre> + </div> + returns an empty string.</dd> +</dl> +<section class="Ss"> +<h2 class="Ss" id="Aggregation_Functions"><a class="permalink" href="#Aggregation_Functions">Aggregation + Functions</a></h2> +<dl class="Bl-tag Bl-compact"> + <dt id="avg"><a class="permalink" href="#avg"><code class="Fn">avg</code></a>(<var class="Fa">value</var>)</dt> + <dd>Average</dd> + <dt id="count"><a class="permalink" href="#count"><code class="Fn">count</code></a>()</dt> + <dd>Count</dd> + <dt id="llquantize"><a class="permalink" href="#llquantize"><code class="Fn">llquantize</code></a>(<var class="Fa">value</var>, + <var class="Fa">factor</var>, <var class="Fa">low</var>, + <var class="Fa">high</var>, <var class="Fa">nsteps</var>)</dt> + <dd>Log-linear quantization</dd> + <dt id="lquantize"><a class="permalink" href="#lquantize"><code class="Fn">lquantize</code></a>(<var class="Fa">value</var>, + <var class="Fa">low</var>, <var class="Fa">high</var>, + <var class="Fa">nsteps</var>)</dt> + <dd>Linear quantization</dd> + <dt id="max"><a class="permalink" href="#max"><code class="Fn">max</code></a>(<var class="Fa">value</var>)</dt> + <dd>Maximum</dd> + <dt id="min"><a class="permalink" href="#min"><code class="Fn">min</code></a>(<var class="Fa">value</var>)</dt> + <dd>Minimum</dd> + <dt id="quantize"><a class="permalink" href="#quantize"><code class="Fn">quantize</code></a>(<var class="Fa">value</var>)</dt> + <dd>Power-of-two frequency distribution</dd> + <dt id="stddev"><a class="permalink" href="#stddev"><code class="Fn">stddev</code></a>(<var class="Fa">value</var>)</dt> + <dd>Standard deviation</dd> + <dt id="sum"><a class="permalink" href="#sum"><code class="Fn">sum</code></a>(<var class="Fa">value</var>)</dt> + <dd>Sum</dd> +</dl> +</section> +<section class="Ss"> +<h2 class="Ss" id="Kernel_Destructive_Functions"><a class="permalink" href="#Kernel_Destructive_Functions">Kernel + Destructive Functions</a></h2> +<p class="Pp">By default, <a class="Xr">dtrace(1)</a> does not permit the use of + destructive actions.</p> +<dl class="Bl-tag"> + <dt id="breakpoint"><a class="permalink" href="#breakpoint"><code class="Fn">breakpoint</code></a>()</dt> + <dd>Set a kernel breakpoint and transfer control to the + <a class="Xr">ddb(4)</a> kernel debugger.</dd> + <dt id="chill"><a class="permalink" href="#chill"><code class="Fn">chill</code></a>(<var class="Fa">nanoseconds</var>)</dt> + <dd>Spin on the CPU for the specified number of + <var class="Fa">nanoseconds</var>.</dd> + <dt id="panic"><a class="permalink" href="#panic"><code class="Fn">panic</code></a>()</dt> + <dd>Panic the kernel.</dd> +</dl> +</section> +</section> +<section class="Sh"> +<h1 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h1> +<dl class="Bl-tag"> + <dt><span class="Pa">/usr/share/dtrace</span></dt> + <dd>DTrace scripts shipped with <span class="Ux">FreeBSD</span> base.</dd> +</dl> +</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">awk(1)</a>, <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/">https://illumos.org/books/dtrace/</a>, + <span class="RsD">2008</span>.</cite></p> +<p class="Pp"><cite class="Rs"><span class="RsA">Brendan Gregg</span> and + <span class="RsA">Jim Mauro</span>, <i class="RsB">DTrace: Dynamic Tracing + in Oracle Solaris, Mac OS X and FreeBSD</i>, <i class="RsI">Prentice + Hall</i>, + <a class="RsU" href="https://www.brendangregg.com/dtracebook/">https://www.brendangregg.com/dtracebook/</a>, + <span class="RsD">2011</span>.</cite></p> +<p class="Pp"><cite class="Rs"><span class="RsA">George Neville-Neil</span>, + <span class="RsA">Jonathan Anderson</span>, <span class="RsA">Graeme + Jenkinson</span>, <span class="RsA">Brian Kidney</span>, + <span class="RsA">Domagoj Stolfa</span>, <span class="RsA">Arun + Thomas</span>, and <span class="RsA">Robert N. M. Watson</span>, + <span class="RsT">Univeristy of Cambridge Computer Laboratory</span>, + <span class="RsR">OpenDTrace Specification version 1.0</span>, + <a class="RsU" href="https://www.cl.cam.ac.uk/techreports/UCAM-CL-TR-924.pdf">https://www.cl.cam.ac.uk/techreports/UCAM-CL-TR-924.pdf</a>, + <span class="RsC">Cambridge, United Kingdom</span>, <span class="RsD">August + 2018</span>.</cite></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">This manual page first appeared in <span class="Ux">FreeBSD + 15.0</span>.</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="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1> +<p class="Pp">The <var class="Va">cwd</var> variable which typically provides + the current working directory is not supported on + <span class="Ux">FreeBSD</span> at the moment.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">October 28, 2025</td> + <td class="foot-os">FreeBSD 15.0</td> + </tr> +</table> |