diff options
Diffstat (limited to 'static/freebsd/man9/SDT.9 4.html')
| -rw-r--r-- | static/freebsd/man9/SDT.9 4.html | 460 |
1 files changed, 0 insertions, 460 deletions
diff --git a/static/freebsd/man9/SDT.9 4.html b/static/freebsd/man9/SDT.9 4.html deleted file mode 100644 index 0136d64e..00000000 --- a/static/freebsd/man9/SDT.9 4.html +++ /dev/null @@ -1,460 +0,0 @@ -<table class="head"> - <tr> - <td class="head-ltitle">SDT(9)</td> - <td class="head-vol">Kernel Developer's Manual</td> - <td class="head-rtitle">SDT(9)</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">SDT</code> — <span class="Nd">a DTrace - framework for adding statically-defined tracing probes</span></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> -<p class="Pp"><code class="In">#include - <<a class="In">sys/param.h</a>></code> - <br/> - <code class="In">#include <<a class="In">sys/queue.h</a>></code> - <br/> - <code class="In">#include <<a class="In">sys/sdt.h</a>></code></p> -<p class="Pp"><code class="Fn">SDT_PROVIDER_DECLARE</code>(<var class="Fa" style="white-space: nowrap;">prov</var>);</p> -<p class="Pp"><code class="Fn">SDT_PROVIDER_DEFINE</code>(<var class="Fa" style="white-space: nowrap;">prov</var>);</p> -<p class="Pp"><code class="Fn">SDT_PROBE_DECLARE</code>(<var class="Fa" style="white-space: nowrap;">prov</var>, - <var class="Fa" style="white-space: nowrap;">mod</var>, - <var class="Fa" style="white-space: nowrap;">func</var>, - <var class="Fa" style="white-space: nowrap;">name</var>);</p> -<p class="Pp"><code class="Fn">SDT_PROBE_DEFINE</code>(<var class="Fa" style="white-space: nowrap;">prov</var>, - <var class="Fa" style="white-space: nowrap;">mod</var>, - <var class="Fa" style="white-space: nowrap;">func</var>, - <var class="Fa" style="white-space: nowrap;">name</var>);</p> -<p class="Pp"><code class="Fn">SDT_PROBE_DEFINE0</code>(<var class="Fa" style="white-space: nowrap;">prov</var>, - <var class="Fa" style="white-space: nowrap;">mod</var>, - <var class="Fa" style="white-space: nowrap;">func</var>, - <var class="Fa" style="white-space: nowrap;">name</var>);</p> -<p class="Pp"><code class="Fn">SDT_PROBE_DEFINE1</code>(<var class="Fa" style="white-space: nowrap;">prov</var>, - <var class="Fa" style="white-space: nowrap;">mod</var>, - <var class="Fa" style="white-space: nowrap;">func</var>, - <var class="Fa" style="white-space: nowrap;">name</var>, - <var class="Fa" style="white-space: nowrap;">arg0</var>);</p> -<p class="Pp"><code class="Fn">SDT_PROBE_DEFINE2</code>(<var class="Fa" style="white-space: nowrap;">prov</var>, - <var class="Fa" style="white-space: nowrap;">mod</var>, - <var class="Fa" style="white-space: nowrap;">func</var>, - <var class="Fa" style="white-space: nowrap;">name</var>, - <var class="Fa" style="white-space: nowrap;">arg0</var>, - <var class="Fa" style="white-space: nowrap;">arg1</var>);</p> -<p class="Pp"><code class="Fn">SDT_PROBE_DEFINE3</code>(<var class="Fa" style="white-space: nowrap;">prov</var>, - <var class="Fa" style="white-space: nowrap;">mod</var>, - <var class="Fa" style="white-space: nowrap;">func</var>, - <var class="Fa" style="white-space: nowrap;">name</var>, - <var class="Fa" style="white-space: nowrap;">arg0</var>, - <var class="Fa" style="white-space: nowrap;">arg1</var>, - <var class="Fa" style="white-space: nowrap;">arg2</var>);</p> -<p class="Pp"><code class="Fn">SDT_PROBE_DEFINE4</code>(<var class="Fa" style="white-space: nowrap;">prov</var>, - <var class="Fa" style="white-space: nowrap;">mod</var>, - <var class="Fa" style="white-space: nowrap;">func</var>, - <var class="Fa" style="white-space: nowrap;">name</var>, - <var class="Fa" style="white-space: nowrap;">arg0</var>, - <var class="Fa" style="white-space: nowrap;">arg1</var>, - <var class="Fa" style="white-space: nowrap;">arg2</var>, - <var class="Fa" style="white-space: nowrap;">arg3</var>);</p> -<p class="Pp"><code class="Fn">SDT_PROBE_DEFINE5</code>(<var class="Fa" style="white-space: nowrap;">prov</var>, - <var class="Fa" style="white-space: nowrap;">mod</var>, - <var class="Fa" style="white-space: nowrap;">func</var>, - <var class="Fa" style="white-space: nowrap;">name</var>, - <var class="Fa" style="white-space: nowrap;">arg0</var>, - <var class="Fa" style="white-space: nowrap;">arg1</var>, - <var class="Fa" style="white-space: nowrap;">arg2</var>, - <var class="Fa" style="white-space: nowrap;">arg3</var>, - <var class="Fa" style="white-space: nowrap;">arg4</var>);</p> -<p class="Pp"><code class="Fn">SDT_PROBE_DEFINE6</code>(<var class="Fa" style="white-space: nowrap;">prov</var>, - <var class="Fa" style="white-space: nowrap;">mod</var>, - <var class="Fa" style="white-space: nowrap;">func</var>, - <var class="Fa" style="white-space: nowrap;">name</var>, - <var class="Fa" style="white-space: nowrap;">arg0</var>, - <var class="Fa" style="white-space: nowrap;">arg1</var>, - <var class="Fa" style="white-space: nowrap;">arg2</var>, - <var class="Fa" style="white-space: nowrap;">arg3</var>, - <var class="Fa" style="white-space: nowrap;">arg4</var>, - <var class="Fa" style="white-space: nowrap;">arg5</var>);</p> -<p class="Pp"><code class="Fn">SDT_PROBE_DEFINE7</code>(<var class="Fa" style="white-space: nowrap;">prov</var>, - <var class="Fa" style="white-space: nowrap;">mod</var>, - <var class="Fa" style="white-space: nowrap;">func</var>, - <var class="Fa" style="white-space: nowrap;">name</var>, - <var class="Fa" style="white-space: nowrap;">arg0</var>, - <var class="Fa" style="white-space: nowrap;">arg1</var>, - <var class="Fa" style="white-space: nowrap;">arg2</var>, - <var class="Fa" style="white-space: nowrap;">arg3</var>, - <var class="Fa" style="white-space: nowrap;">arg4</var>, - <var class="Fa" style="white-space: nowrap;">arg5</var>, - <var class="Fa" style="white-space: nowrap;">arg6</var>);</p> -<p class="Pp"><code class="Fn">SDT_PROBE_DEFINE0_XLATE</code>(<var class="Fa" style="white-space: nowrap;">prov</var>, - <var class="Fa" style="white-space: nowrap;">mod</var>, - <var class="Fa" style="white-space: nowrap;">func</var>, - <var class="Fa" style="white-space: nowrap;">name</var>);</p> -<p class="Pp"><code class="Fn">SDT_PROBE_DEFINE1_XLATE</code>(<var class="Fa" style="white-space: nowrap;">prov</var>, - <var class="Fa" style="white-space: nowrap;">mod</var>, - <var class="Fa" style="white-space: nowrap;">func</var>, - <var class="Fa" style="white-space: nowrap;">name</var>, - <var class="Fa" style="white-space: nowrap;">arg0</var>, - <var class="Fa" style="white-space: nowrap;">xarg0</var>);</p> -<p class="Pp"><code class="Fn">SDT_PROBE_DEFINE2_XLATE</code>(<var class="Fa" style="white-space: nowrap;">prov</var>, - <var class="Fa" style="white-space: nowrap;">mod</var>, - <var class="Fa" style="white-space: nowrap;">func</var>, - <var class="Fa" style="white-space: nowrap;">name</var>, - <var class="Fa" style="white-space: nowrap;">arg0</var>, - <var class="Fa" style="white-space: nowrap;">xarg0</var>, - <var class="Fa" style="white-space: nowrap;">arg1</var>, - <var class="Fa" style="white-space: nowrap;">xarg1</var>);</p> -<p class="Pp"><code class="Fn">SDT_PROBE_DEFINE3_XLATE</code>(<var class="Fa" style="white-space: nowrap;">prov</var>, - <var class="Fa" style="white-space: nowrap;">mod</var>, - <var class="Fa" style="white-space: nowrap;">func</var>, - <var class="Fa" style="white-space: nowrap;">name</var>, - <var class="Fa" style="white-space: nowrap;">arg0</var>, - <var class="Fa" style="white-space: nowrap;">xarg0</var>, - <var class="Fa" style="white-space: nowrap;">arg1</var>, - <var class="Fa" style="white-space: nowrap;">xarg1</var>, - <var class="Fa" style="white-space: nowrap;">arg2</var>, - <var class="Fa" style="white-space: nowrap;">xarg2</var>);</p> -<p class="Pp"><code class="Fn">SDT_PROBE_DEFINE4_XLATE</code>(<var class="Fa" style="white-space: nowrap;">prov</var>, - <var class="Fa" style="white-space: nowrap;">mod</var>, - <var class="Fa" style="white-space: nowrap;">func</var>, - <var class="Fa" style="white-space: nowrap;">name</var>, - <var class="Fa" style="white-space: nowrap;">arg0</var>, - <var class="Fa" style="white-space: nowrap;">xarg0</var>, - <var class="Fa" style="white-space: nowrap;">arg1</var>, - <var class="Fa" style="white-space: nowrap;">xarg1</var>, - <var class="Fa" style="white-space: nowrap;">arg2</var>, - <var class="Fa" style="white-space: nowrap;">xarg2</var>, - <var class="Fa" style="white-space: nowrap;">arg3</var>, - <var class="Fa" style="white-space: nowrap;">xarg3</var>);</p> -<p class="Pp"><code class="Fn">SDT_PROBE_DEFINE5_XLATE</code>(<var class="Fa" style="white-space: nowrap;">prov</var>, - <var class="Fa" style="white-space: nowrap;">mod</var>, - <var class="Fa" style="white-space: nowrap;">func</var>, - <var class="Fa" style="white-space: nowrap;">name</var>, - <var class="Fa" style="white-space: nowrap;">arg0</var>, - <var class="Fa" style="white-space: nowrap;">xarg0</var>, - <var class="Fa" style="white-space: nowrap;">arg1</var>, - <var class="Fa" style="white-space: nowrap;">xarg1</var>, - <var class="Fa" style="white-space: nowrap;">arg2</var>, - <var class="Fa" style="white-space: nowrap;">xarg2</var>, - <var class="Fa" style="white-space: nowrap;">arg3</var>, - <var class="Fa" style="white-space: nowrap;">xarg3</var>, - <var class="Fa" style="white-space: nowrap;">arg4</var>, - <var class="Fa" style="white-space: nowrap;">xarg4</var>);</p> -<p class="Pp"><code class="Fn">SDT_PROBE_DEFINE6_XLATE</code>(<var class="Fa" style="white-space: nowrap;">prov</var>, - <var class="Fa" style="white-space: nowrap;">mod</var>, - <var class="Fa" style="white-space: nowrap;">func</var>, - <var class="Fa" style="white-space: nowrap;">name</var>, - <var class="Fa" style="white-space: nowrap;">arg0</var>, - <var class="Fa" style="white-space: nowrap;">xarg0</var>, - <var class="Fa" style="white-space: nowrap;">arg1</var>, - <var class="Fa" style="white-space: nowrap;">xarg1</var>, - <var class="Fa" style="white-space: nowrap;">arg2</var>, - <var class="Fa" style="white-space: nowrap;">xarg2</var>, - <var class="Fa" style="white-space: nowrap;">arg3</var>, - <var class="Fa" style="white-space: nowrap;">xarg3</var>, - <var class="Fa" style="white-space: nowrap;">arg4</var>, - <var class="Fa" style="white-space: nowrap;">xarg4</var>, - <var class="Fa" style="white-space: nowrap;">arg5</var>, - <var class="Fa" style="white-space: nowrap;">xarg5</var>);</p> -<p class="Pp"><code class="Fn">SDT_PROBE_DEFINE7_XLATE</code>(<var class="Fa" style="white-space: nowrap;">prov</var>, - <var class="Fa" style="white-space: nowrap;">mod</var>, - <var class="Fa" style="white-space: nowrap;">func</var>, - <var class="Fa" style="white-space: nowrap;">name</var>, - <var class="Fa" style="white-space: nowrap;">arg0</var>, - <var class="Fa" style="white-space: nowrap;">xarg0</var>, - <var class="Fa" style="white-space: nowrap;">arg1</var>, - <var class="Fa" style="white-space: nowrap;">xarg1</var>, - <var class="Fa" style="white-space: nowrap;">arg2</var>, - <var class="Fa" style="white-space: nowrap;">xarg2</var>, - <var class="Fa" style="white-space: nowrap;">arg3</var>, - <var class="Fa" style="white-space: nowrap;">xarg3</var>, - <var class="Fa" style="white-space: nowrap;">arg4</var>, - <var class="Fa" style="white-space: nowrap;">xarg4</var>, - <var class="Fa" style="white-space: nowrap;">arg5</var>, - <var class="Fa" style="white-space: nowrap;">xarg5</var>, - <var class="Fa" style="white-space: nowrap;">arg6</var>, - <var class="Fa" style="white-space: nowrap;">xarg6</var>);</p> -<p class="Pp"><code class="Fn">SDT_PROBE0</code>(<var class="Fa" style="white-space: nowrap;">prov</var>, - <var class="Fa" style="white-space: nowrap;">mod</var>, - <var class="Fa" style="white-space: nowrap;">func</var>, - <var class="Fa" style="white-space: nowrap;">name</var>);</p> -<p class="Pp"><code class="Fn">SDT_PROBE1</code>(<var class="Fa" style="white-space: nowrap;">prov</var>, - <var class="Fa" style="white-space: nowrap;">mod</var>, - <var class="Fa" style="white-space: nowrap;">func</var>, - <var class="Fa" style="white-space: nowrap;">name</var>, - <var class="Fa" style="white-space: nowrap;">arg0</var>);</p> -<p class="Pp"><code class="Fn">SDT_PROBE2</code>(<var class="Fa" style="white-space: nowrap;">prov</var>, - <var class="Fa" style="white-space: nowrap;">mod</var>, - <var class="Fa" style="white-space: nowrap;">func</var>, - <var class="Fa" style="white-space: nowrap;">name</var>, - <var class="Fa" style="white-space: nowrap;">arg0</var>, - <var class="Fa" style="white-space: nowrap;">arg1</var>);</p> -<p class="Pp"><code class="Fn">SDT_PROBE3</code>(<var class="Fa" style="white-space: nowrap;">prov</var>, - <var class="Fa" style="white-space: nowrap;">mod</var>, - <var class="Fa" style="white-space: nowrap;">func</var>, - <var class="Fa" style="white-space: nowrap;">name</var>, - <var class="Fa" style="white-space: nowrap;">arg0</var>, - <var class="Fa" style="white-space: nowrap;">arg1</var>, - <var class="Fa" style="white-space: nowrap;">arg2</var>);</p> -<p class="Pp"><code class="Fn">SDT_PROBE4</code>(<var class="Fa" style="white-space: nowrap;">prov</var>, - <var class="Fa" style="white-space: nowrap;">mod</var>, - <var class="Fa" style="white-space: nowrap;">func</var>, - <var class="Fa" style="white-space: nowrap;">name</var>, - <var class="Fa" style="white-space: nowrap;">arg0</var>, - <var class="Fa" style="white-space: nowrap;">arg1</var>, - <var class="Fa" style="white-space: nowrap;">arg2</var>, - <var class="Fa" style="white-space: nowrap;">arg3</var>);</p> -<p class="Pp"><code class="Fn">SDT_PROBE5</code>(<var class="Fa" style="white-space: nowrap;">prov</var>, - <var class="Fa" style="white-space: nowrap;">mod</var>, - <var class="Fa" style="white-space: nowrap;">func</var>, - <var class="Fa" style="white-space: nowrap;">name</var>, - <var class="Fa" style="white-space: nowrap;">arg0</var>, - <var class="Fa" style="white-space: nowrap;">arg1</var>, - <var class="Fa" style="white-space: nowrap;">arg2</var>, - <var class="Fa" style="white-space: nowrap;">arg3</var>, - <var class="Fa" style="white-space: nowrap;">arg4</var>);</p> -<p class="Pp"><code class="Fn">SDT_PROBE6</code>(<var class="Fa" style="white-space: nowrap;">prov</var>, - <var class="Fa" style="white-space: nowrap;">mod</var>, - <var class="Fa" style="white-space: nowrap;">func</var>, - <var class="Fa" style="white-space: nowrap;">name</var>, - <var class="Fa" style="white-space: nowrap;">arg0</var>, - <var class="Fa" style="white-space: nowrap;">arg1</var>, - <var class="Fa" style="white-space: nowrap;">arg2</var>, - <var class="Fa" style="white-space: nowrap;">arg3</var>, - <var class="Fa" style="white-space: nowrap;">arg4</var>, - <var class="Fa" style="white-space: nowrap;">arg5</var>);</p> -<p class="Pp"><code class="Fn">SDT_PROBE7</code>(<var class="Fa" style="white-space: nowrap;">prov</var>, - <var class="Fa" style="white-space: nowrap;">mod</var>, - <var class="Fa" style="white-space: nowrap;">func</var>, - <var class="Fa" style="white-space: nowrap;">name</var>, - <var class="Fa" style="white-space: nowrap;">arg0</var>, - <var class="Fa" style="white-space: nowrap;">arg1</var>, - <var class="Fa" style="white-space: nowrap;">arg2</var>, - <var class="Fa" style="white-space: nowrap;">arg3</var>, - <var class="Fa" style="white-space: nowrap;">arg4</var>, - <var class="Fa" style="white-space: nowrap;">arg5</var>, - <var class="Fa" style="white-space: nowrap;">arg6</var>);</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> -<p class="Pp">The <code class="Nm">SDT</code> macros allow programmers to define - static trace points in kernel code. These trace points are used by the - <code class="Nm">SDT</code> framework to create DTrace probes, allowing the - code to be instrumented using <a class="Xr">dtrace(1)</a>. By default, - <code class="Nm">SDT</code> trace points are disabled and have no effect on - the surrounding code. When a DTrace probe corresponding to a given trace - point is enabled, threads that execute the trace point will call a handler - and cause the probe to fire. Moreover, trace points can take arguments, - making it possible to pass data to the DTrace framework when an enabled - probe fires.</p> -<p class="Pp">Multiple trace points may correspond to a single DTrace probe, - allowing programmers to create DTrace probes that correspond to logical - system events rather than tying probes to specific code execution paths. For - instance, a DTrace probe corresponding to the arrival of an IP packet into - the network stack may be defined using two <code class="Nm">SDT</code> trace - points: one for IPv4 packets and one for IPv6 packets.</p> -<p class="Pp">In addition to defining DTrace probes, the - <code class="Nm">SDT</code> macros allow programmers to define new DTrace - providers, making it possible to namespace logically-related probes. An - example is FreeBSD's sctp provider, which contains - <code class="Nm">SDT</code> probes for FreeBSD's <a class="Xr">sctp(4)</a> - implementation.</p> -<p class="Pp" id="SDT_PROVIDER_DECLARE">The - <a class="permalink" href="#SDT_PROVIDER_DECLARE"><code class="Fn">SDT_PROVIDER_DECLARE</code></a>() - and - <a class="permalink" href="#SDT_PROVIDER_DEFINE"><code class="Fn" id="SDT_PROVIDER_DEFINE">SDT_PROVIDER_DEFINE</code></a>() - macros are used respectively to declare and define a DTrace provider named - <var class="Ar">prov</var> with the <code class="Nm">SDT</code> framework. A - provider need only be defined once; however, the provider must be declared - before defining any <code class="Nm">SDT</code> probes belonging to that - provider.</p> -<p class="Pp" id="SDT_PROBE_DECLARE">Similarly, the - <a class="permalink" href="#SDT_PROBE_DECLARE"><code class="Fn">SDT_PROBE_DECLARE</code></a>() - and <code class="Fn">SDT_PROBE_DEFINE*</code>() macros are used to declare - and define DTrace probes using the <code class="Nm">SDT</code> framework. - Once a probe has been defined, trace points for that probe may be added to - kernel code. DTrace probe identifiers consist of a provider, module, - function and name, all of which may be specified in the - <code class="Nm">SDT</code> probe definition. Note that probes should not - specify a module name: the module name of a probe is used to determine - whether or not it should be destroyed when a kernel module is unloaded. See - the <a class="Sx" href="#BUGS">BUGS</a> section. Note in particular that - probes must not be defined across multiple kernel modules.</p> -<p class="Pp" id="SDT_*">If ‘<code class="Li">-</code>’ character - (dash) is wanted in a probe name, then it should be represented as - ‘<code class="Li">__</code>’ (double underscore) in the probe - <var class="Ar">name</var> parameter passed to various - <a class="permalink" href="#SDT_*"><code class="Fn">SDT_*</code></a>() - macros, because of technical reasons (a dash is not valid in C - identifiers).</p> -<p class="Pp" id="SDT_PROBE_DEFINE*">The - <a class="permalink" href="#SDT_PROBE_DEFINE*"><code class="Fn">SDT_PROBE_DEFINE*</code></a>() - macros also allow programmers to declare the types of the arguments that are - passed to probes. This is optional; if the argument types are omitted - (through use of the - <a class="permalink" href="#SDT_PROBE_DEFINE"><code class="Fn" id="SDT_PROBE_DEFINE">SDT_PROBE_DEFINE</code></a>() - macro), users wishing to make use of the arguments will have to manually - cast them to the correct types in their D scripts. It is strongly - recommended that probe definitions include a declaration of their argument - types.</p> -<p class="Pp" id="SDT_PROBE_DEFINE*_XLATE">The - <a class="permalink" href="#SDT_PROBE_DEFINE*_XLATE"><code class="Fn">SDT_PROBE_DEFINE*_XLATE</code></a>() - macros are used for probes whose argument types are to be dynamically - translated to the types specified by the corresponding - <var class="Ar">xarg</var> arguments. This is mainly useful when porting - probe definitions from other operating systems. As seen by - <a class="Xr">dtrace(1)</a>, the arguments of a probe defined using these - macros will have types which match the <var class="Ar">xarg</var> types in - the probe definition. However, the arguments passed in at the trace point - will have types matching the native argument types in the probe definition, - and thus the native type is dynamically translated to the translated type. - So long as an appropriate translator is defined in - <span class="Pa">/usr/lib/dtrace</span>, scripts making use of the probe - need not concern themselves with the underlying type of a given - <code class="Nm">SDT</code> probe argument.</p> -<p class="Pp" id="SDT_PROBE*">The - <a class="permalink" href="#SDT_PROBE*"><code class="Fn">SDT_PROBE*</code></a>() - macros are used to create <code class="Nm">SDT</code> trace points. They are - meant to be added to executable code and can be used to instrument the code - in which they are called.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="PROVIDERS"><a class="permalink" href="#PROVIDERS">PROVIDERS</a></h1> -<p class="Pp">A number of kernel DTrace providers are available. In general, - these providers define stable interfaces and should be treated as such: - existing D scripts may be broken if a probe is renamed or its arguments are - modified. However, it is often useful to define ad-hoc - <code class="Nm">SDT</code> probes for debugging a subsystem or driver. - Similarly, a developer may wish to provide a group of - <code class="Nm">SDT</code> probes without committing to their future - stability. Such probes should be added to the - ‘<code class="Li">sdt</code>’ provider instead of defining a - new provider.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> -<p class="Pp">The DTrace providers available on the current system can be listed - with</p> -<div class="Bd Pp Bd-indent Li"> -<pre>dtrace -l | sed 1d | awk '{print $2}' | sort -u</pre> -</div> -<p class="Pp">A detailed list of the probes offered by a given provider can be - obtained by specifying the provider using the <code class="Fl">-P</code> - flag. For example, to view the probes and argument types for the - ‘<code class="Li">sched</code>’ provider, run</p> -<div class="Bd Pp Bd-indent Li"> -<pre>dtrace -lv -P sched</pre> -</div> -<p class="Pp">The following probe definition will create a DTrace probe called - ‘<code class="Li">icmp:::receive-unreachable</code>’, which - would hypothetically be triggered when the kernel receives an ICMP packet of - type Destination Unreachable:</p> -<div class="Bd Pp Bd-indent Li"> -<pre>SDT_PROVIDER_DECLARE(icmp); - -SDT_PROBE_DEFINE1(icmp, , , receive__unreachable, - "struct icmp *"); - -</pre> -</div> -This particular probe would take a single argument: a pointer to the struct - containing the ICMP header for the packet. Note that the module name of this - probe is not specified. -<p class="Pp">Consider a DTrace probe which fires when the network stack - receives an IP packet. Such a probe would be defined by multiple - tracepoints:</p> -<div class="Bd Pp Bd-indent Li"> -<pre>SDT_PROBE_DEFINE3(ip, , , receive, "struct ifnet *", - "struct ip *", "struct ip6_hdr *"); - -int -ip_input(struct mbuf *m) -{ - struct ip *ip; - ... - ip = mtod(m, struct ip *); - SDT_PROBE3(ip, , , receive, m->m_pkthdr.rcvif, ip, NULL); - ... -} - -int -ip6_input(struct mbuf *m) -{ - struct ip6_hdr *ip6; - ... - ip6 = mtod(m, struct ip6_hdr *); - SDT_PROBE3(ip, , , receive, m->m_pkthdr.rcvif, NULL, ip6); - ... -} - -</pre> -</div> -In particular, the probe should fire when the kernel receives either an IPv4 - packet or an IPv6 packet. -<p class="Pp">Consider the ICMP probe discussed above. We note that its second - argument is of type <var class="Ar">struct icmp</var>, which is a type - defined in the FreeBSD kernel to represent the ICMP header of an ICMP - packet, defined in RFC 792. Linux has a corresponding type, - <var class="Ar">struct icmphdr</var>, for the same purpose, but its field - names differ from FreeBSD's <var class="Ar">struct icmp</var>. Similarly, - illumos defines the <var class="Ar">icmph_t</var> type, again with different - field names. Even with the - ‘<code class="Li">icmp:::pkt-receive</code>’ probes defined in - all three operating systems, one would still have to write OS-specific - scripts to extract a given field out of the ICMP header argument. - Dynamically-translated types solve this problem: one can define an - OS-independent <a class="Xr">c(7)</a> struct to represent an ICMP header, - say <var class="Ar">struct icmp_hdr_dt</var>, and define translators from - each of the three OS-specific types to <var class="Ar">struct - icmp_hdr_dt</var>, all in the <a class="Xr">dtrace(1)</a> library path. Then - the FreeBSD probe above can be defined with:</p> -<div class="Bd Pp Bd-indent Li"> -<pre>SDT_PROBE_DEFINE1_XLATE(ip, , , receive, "struct icmp *", - "struct icmp_hdr_dt *");</pre> -</div> -</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">dtrace_io(4)</a>, - <a class="Xr">dtrace_ip(4)</a>, <a class="Xr">dtrace_proc(4)</a>, - <a class="Xr">dtrace_sched(4)</a>, <a class="Xr">dtrace_tcp(4)</a>, - <a class="Xr">dtrace_udp(4)</a></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> -<p class="Pp">DTrace and the <code class="Nm">SDT</code> framework were - originally ported to FreeBSD from Solaris by <span class="An">John - Birrell</span> - <<a class="Mt" href="mailto:jb@FreeBSD.org">jb@FreeBSD.org</a>>. This - manual page was written by <span class="An">Mark Johnston</span> - <<a class="Mt" href="mailto:markj@FreeBSD.org">markj@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 <code class="Nm">SDT</code> macros allow the module and - function names of a probe to be specified as part of a probe definition. The - DTrace framework uses the module name of probes to determine which probes - should be destroyed when a kernel module is unloaded, so the module name of - a probe should match the name of the module in which its defined. - <code class="Nm">SDT</code> will set the module name properly if it is left - unspecified in the probe definition; see the - <a class="Sx" href="#EXAMPLES">EXAMPLES</a> section.</p> -<p class="Pp">One of the goals of the original <code class="Nm">SDT</code> - implementation (and by extension, of FreeBSD's port) is that inactive - <code class="Nm">SDT</code> probes should have no performance impact. This - is unfortunately not the case; <code class="Nm">SDT</code> trace points will - add a small but non-zero amount of latency to the code in which they are - defined. A more sophisticated implementation of the probes will help - alleviate this problem.</p> -</section> -</div> -<table class="foot"> - <tr> - <td class="foot-date">April 18, 2015</td> - <td class="foot-os">FreeBSD 15.0</td> - </tr> -</table> |