static/freebsd/man4/dtrace_udplite.4 3.html


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204

<table class="head">
  <tr>
    <td class="head-ltitle">DTRACE_UDPLITE(4)</td>
    <td class="head-vol">Device Drivers Manual</td>
    <td class="head-rtitle">DTRACE_UDPLITE(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_udplite</code> &#x2014; <span class="Nd">a
    DTrace provider for tracing events related to the UDP-Lite
  protocol</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<p class="Pp"><code class="Fn">udplite:::receive</code>(<var class="Fa" style="white-space: nowrap;">pktinfo_t
    *</var>, <var class="Fa" style="white-space: nowrap;">csinfo_t *</var>,
    <var class="Fa" style="white-space: nowrap;">ipinfo_t *</var>,
    <var class="Fa" style="white-space: nowrap;">udplitesinfo_t *</var>,
    <var class="Fa" style="white-space: nowrap;">udpliteinfo_t *</var>);</p>
<p class="Pp"><code class="Fn">udplite:::send</code>(<var class="Fa" style="white-space: nowrap;">pktinfo_t
    *</var>, <var class="Fa" style="white-space: nowrap;">csinfo_t *</var>,
    <var class="Fa" style="white-space: nowrap;">ipinfo_t *</var>,
    <var class="Fa" style="white-space: nowrap;">udplitesinfo_t *</var>,
    <var class="Fa" style="white-space: nowrap;">udpliteinfo_t *</var>);</p>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">The DTrace <code class="Nm">udplite</code> provider allows users
    to trace events in the <a class="Xr">udplite(4)</a> protocol implementation.
    The
    <a class="permalink" href="#udplite:::send"><code class="Fn" id="udplite:::send">udplite:::send</code></a>()
    probe fires whenever the kernel prepares to transmit a UDP-Lite packet, and
    the
    <a class="permalink" href="#udplite:::receive"><code class="Fn" id="udplite:::receive">udplite:::receive</code></a>()
    probe fires whenever the kernel receives a UDP-Lite packet, unless the
    UDP-Lite header is incomplete, the destination port is 0, the length field
    is invalid, or the checksum is wrong. The arguments to these probes can be
    used to obtain detailed information about the IP and UDP-Lite headers of the
    corresponding packet.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="ARGUMENTS"><a class="permalink" href="#ARGUMENTS">ARGUMENTS</a></h1>
<p class="Pp">The <var class="Vt">pktinfo_t</var> argument is currently
    unimplemented and is included for compatibility with other implementations
    of this provider. Its fields are:</p>
<div class="Bd-indent">
<dl class="Bl-tag">
  <dt><var class="Vt">uintptr_t pkt_addr</var></dt>
  <dd>Always set to 0.</dd>
</dl>
</div>
<p class="Pp">The <var class="Vt">csinfo_t</var> argument is currently
    unimplemented and is included for compatibility with other implementations
    of this provider. Its fields are:</p>
<div class="Bd-indent">
<dl class="Bl-tag">
  <dt><var class="Vt">uintptr_t cs_addr</var></dt>
  <dd>Always set to 0.</dd>
  <dt><var class="Vt">uint64_t cs_cid</var></dt>
  <dd>A pointer to the <var class="Vt">struct inpcb</var> for this packet, or
      <code class="Dv">NULL</code>.</dd>
  <dt><var class="Vt">pid_t cs_pid</var></dt>
  <dd>Always set to 0.</dd>
</dl>
</div>
<p class="Pp">The <var class="Vt">ipinfo_t</var> argument contains IP fields
    common to both IPv4 and IPv6 packets. Its fields are:</p>
<div class="Bd-indent">
<dl class="Bl-tag">
  <dt><var class="Vt">uint8_t ip_ver</var></dt>
  <dd>IP version of the packet, 4 for IPv4 packets and 6 for IPv6 packets.</dd>
  <dt><var class="Vt">uint32_t ip_plength</var></dt>
  <dd>IP payload size. This does not include the size of the IP header or IPv6
      option headers.</dd>
  <dt><var class="Vt">string ip_saddr</var></dt>
  <dd>IP source address.</dd>
  <dt><var class="Vt">string ip_daddr</var></dt>
  <dd>IP destination address.</dd>
</dl>
</div>
<p class="Pp">The <var class="Vt">udplitesinfo_t</var> argument contains the
    state of the UDP-Lite connection associated with the packet. Its fields
  are:</p>
<div class="Bd-indent">
<dl class="Bl-tag">
  <dt><var class="Vt">uintptr_t udplites_addr</var></dt>
  <dd>Pointer to the <var class="Vt">struct inpcb</var> containing the IP state
      for the associated socket.</dd>
  <dt><var class="Vt">uint16_t udplites_lport</var></dt>
  <dd>Local UDP-Lite port.</dd>
  <dt><var class="Vt">uint16_t udplites_rport</var></dt>
  <dd>Remote UDP-Lite port.</dd>
  <dt><var class="Vt">string udplites_laddr</var></dt>
  <dd>Local IPv4 or IPv6 address.</dd>
  <dt><var class="Vt">string udplites_raddr</var></dt>
  <dd>Remote IPv4 or IPv6 address.</dd>
</dl>
</div>
<p class="Pp">The <var class="Vt">udpliteinfo_t</var> argument is the raw
    UDP-Lite header of the packet, with all fields in host order. Its fields
    are:</p>
<div class="Bd-indent">
<dl class="Bl-tag">
  <dt><var class="Vt">uint16_t udplite_sport</var></dt>
  <dd>Source UDP-Lite port.</dd>
  <dt><var class="Vt">uint16_t udplite_dport</var></dt>
  <dd>Destination UDP-Lite port.</dd>
  <dt><var class="Vt">uint16_t udplite_coverage</var></dt>
  <dd>Checksum coverage of the UDP-Lite header, in bytes, or 0 for full
      coverage.</dd>
  <dt><var class="Vt">uint16_t udplite_checksum</var></dt>
  <dd>A checksum of the UDP-Lite header and payload, or 0 if no checksum was
      calculated.</dd>
  <dt><var class="Vt">struct udplitehdr *udplite_hdr</var></dt>
  <dd>A pointer to the raw UDP-Lite header.</dd>
</dl>
</div>
</section>
<section class="Sh">
<h1 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h1>
<dl class="Bl-tag Bl-compact">
  <dt><span class="Pa">/usr/lib/dtrace/udplite.d</span></dt>
  <dd>DTrace type and translator definitions for the
      <code class="Nm">udplite</code> provider.</dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1>
<p class="Pp">The following script counts transmitted packets by destination
    port.</p>
<div class="Bd Pp Bd-indent Li">
<pre>udplite:::send
{
        @num[args[4]-&gt;udplite_dport] = count();
}</pre>
</div>
<p class="Pp">This script will print some details of each UDP-Lite packet as it
    is sent or received by the kernel:</p>
<div class="Bd Pp Bd-indent Li">
<pre>#pragma D option quiet
#pragma D option switchrate=10Hz

dtrace:::BEGIN
{
        printf(&quot; %10s %36s    %-36s %6s\n&quot;, &quot;DELTA(us)&quot;, &quot;SOURCE&quot;,
            &quot;DEST&quot;, &quot;COV&quot;);
        last = timestamp;
}

udplite:::send
{
        this-&gt;elapsed = (timestamp - last) / 1000;
        self-&gt;dest = strjoin(strjoin(args[2]-&gt;ip_daddr, &quot;:&quot;),
             lltostr(args[4]-&gt;udplite_dport));
        printf(&quot; %10d %30s:%-5d -&gt; %-36s %6d\n&quot;, this-&gt;elapsed,
            args[2]-&gt;ip_saddr, args[4]-&gt;udplite_sport,
            self-&gt;dest, args[4]-&gt;udplite_coverage);
        last = timestamp;
}

udplite:::receive
{
        this-&gt;elapsed = (timestamp - last) / 1000;
        self-&gt;dest = strjoin(strjoin(args[2]-&gt;ip_saddr, &quot;:&quot;),
             lltostr(args[4]-&gt;udplite_sport));
        printf(&quot; %10d %30s:%-5d &lt;- %-36s %6d\n&quot;, this-&gt;elapsed,
            args[2]-&gt;ip_daddr, args[4]-&gt;udplite_dport,
            self-&gt;dest, args[4]-&gt;udplite_coverage);
        last = timestamp;
}</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_ip(4)</a>,
    <a class="Xr">dtrace_sctp(4)</a>, <a class="Xr">dtrace_tcp(4)</a>,
    <a class="Xr">dtrace_udp(4)</a>, <a class="Xr">udplite(4)</a>,
    <a class="Xr">SDT(9)</a></p>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
<p class="Pp">The <code class="Nm">udplite</code> provider first appeared in
    <span class="Ux">FreeBSD</span> 12.0.</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">Mark
    Johnston</span>
    &lt;<a class="Mt" href="mailto:markj@FreeBSD.org">markj@FreeBSD.org</a>&gt;
    and
  <br/>
  <span class="An">Michael Tuexen</span>
    &lt;<a class="Mt" href="mailto:tuexen@FreeBSD.org">tuexen@FreeBSD.org</a>&gt;.</p>
</section>
</div>
<table class="foot">
  <tr>
    <td class="foot-date">August 1, 2018</td>
    <td class="foot-os">FreeBSD 15.0</td>
  </tr>
</table>