1 files changed, 203 insertions, 0 deletions
diff --git a/static/freebsd/man4/dtrace_udp.4 b/static/freebsd/man4/dtrace_udp.4
new file mode 100644
index 00000000..2e5c40cc
--- /dev/null
+++ b/static/freebsd/man4/dtrace_udp.4
@@ -0,0 +1,203 @@
+.\" Copyright (c) 2015 Mark Johnston <markj@FreeBSD.org>
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.Dd August 1, 2018
+.Dt DTRACE_UDP 4
+.Os
+.Sh NAME
+.Nm dtrace_udp
+.Nd a DTrace provider for tracing events related to the UDP protocol
+.Sh SYNOPSIS
+.Fn udp:::receive "pktinfo_t *" "csinfo_t *" "ipinfo_t *" "udpsinfo_t *" \
+    "udpinfo_t *"
+.Fn udp:::send "pktinfo_t *" "csinfo_t *" "ipinfo_t *" "udpsinfo_t *" \
+    "udpinfo_t *"
+.Sh DESCRIPTION
+The DTrace
+.Nm udp
+provider allows users to trace events in the
+.Xr udp 4
+protocol implementation.
+The
+.Fn udp:::send
+probe fires whenever the kernel prepares to transmit a UDP packet, and the
+.Fn udp:::receive
+probe fires whenever the kernel receives a UDP packet, unless
+the UDP 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 headers of the corresponding packet.
+.Sh ARGUMENTS
+The
+.Vt pktinfo_t
+argument is currently unimplemented and is included for compatibility with other
+implementations of this provider.
+Its fields are:
+.Bl -tag -width "uintptr_t pkt_addr" -offset indent
+.It Vt uintptr_t pkt_addr
+Always set to 0.
+.El
+.Pp
+The
+.Vt csinfo_t
+argument is currently unimplemented and is included for compatibility with other
+implementations of this provider.
+Its fields are:
+.Bl -tag -width "uintptr_t cs_addr" -offset indent
+.It Vt uintptr_t cs_addr
+Always set to 0.
+.It Vt uint64_t cs_cid
+A pointer to the
+.Vt struct inpcb
+for this packet, or
+.Dv NULL .
+.It Vt pid_t cs_pid
+Always set to 0.
+.El
+.Pp
+The
+.Vt ipinfo_t
+argument contains IP fields common to both IPv4 and IPv6 packets.
+Its fields are:
+.Bl -tag -width "uint32_t ip_plength" -offset indent
+.It Vt uint8_t ip_ver
+IP version of the packet, 4 for IPv4 packets and 6 for IPv6 packets.
+.It Vt uint32_t ip_plength
+IP payload size.
+This does not include the size of the IP header or IPv6 option headers.
+.It Vt string ip_saddr
+IP source address.
+.It Vt string ip_daddr
+IP destination address.
+.El
+.Pp
+The
+.Vt udpsinfo_t
+argument contains the state of the UDP connection associated with the packet.
+Its fields are:
+.Bl -tag -width "uintptr_t udps_addr" -offset indent
+.It Vt uintptr_t udps_addr
+Pointer to the
+.Vt struct inpcb
+containing the IP state for the associated socket.
+.It Vt uint16_t udps_lport
+Local UDP port.
+.It Vt uint16_t udps_rport
+Remote UDP port.
+.It Vt string udps_laddr
+Local IPv4 or IPv6 address.
+.It Vt string udps_raddr
+Remote IPv4 or IPv6 address.
+.El
+.Pp
+The
+.Vt udpinfo_t
+argument is the raw UDP header of the packet, with all fields in host order.
+Its fields are:
+.Bl -tag -width "struct udphdr *udp_hdr" -offset indent
+.It Vt uint16_t udp_sport
+Source UDP port.
+.It Vt uint16_t udp_dport
+Destination UDP port.
+.It Vt uint16_t udp_length
+Length of the UDP header and payload, in bytes.
+.It Vt uint16_t udp_checksum
+A checksum of the UDP header and payload, or 0 if no checksum was calculated.
+.It Vt struct udphdr *udp_hdr
+A pointer to the raw UDP header.
+.El
+.Sh FILES
+.Bl -tag -width "/usr/lib/dtrace/udp.d" -compact
+.It Pa /usr/lib/dtrace/udp.d
+DTrace type and translator definitions for the
+.Nm udp
+provider.
+.El
+.Sh EXAMPLES
+The following script counts transmitted packets by destination port.
+.Bd -literal -offset indent
+udp:::send
+{
+        @num[args[4]->udp_dport] = count();
+}
+.Ed
+.Pp
+This script will print some details of each UDP packet as it is sent or received
+by the kernel:
+.Bd -literal -offset indent
+#pragma D option quiet
+#pragma D option switchrate=10Hz
+
+dtrace:::BEGIN
+{
+        printf(" %10s %36s    %-36s %6s\\n", "DELTA(us)", "SOURCE",
+            "DEST", "BYTES");
+        last = timestamp;
+}
+
+udp:::send
+{
+        this->elapsed = (timestamp - last) / 1000;
+        self->dest = strjoin(strjoin(args[2]->ip_daddr, ":"),
+             lltostr(args[4]->udp_dport));
+        printf(" %10d %30s:%-5d -> %-36s %6d\\n", this->elapsed,
+            args[2]->ip_saddr, args[4]->udp_sport,
+            self->dest, args[4]->udp_length);
+        last = timestamp;
+}
+
+udp:::receive
+{
+        this->elapsed = (timestamp - last) / 1000;
+        self->dest = strjoin(strjoin(args[2]->ip_saddr, ":"),
+             lltostr(args[4]->udp_sport));
+        printf(" %10d %30s:%-5d <- %-36s %6d\\n", this->elapsed,
+            args[2]->ip_daddr, args[4]->udp_dport,
+            self->dest, args[4]->udp_length);
+        last = timestamp;
+}
+.Ed
+.Sh COMPATIBILITY
+This provider is compatible with the
+.Nm udp
+provider in Solaris.
+.Sh SEE ALSO
+.Xr dtrace 1 ,
+.Xr dtrace_ip 4 ,
+.Xr dtrace_sctp 4 ,
+.Xr dtrace_tcp 4 ,
+.Xr dtrace_udplite 4 ,
+.Xr udp 4 ,
+.Xr SDT 9
+.Sh HISTORY
+The
+.Nm udp
+provider first appeared in
+.Fx
+10.0.
+.Sh AUTHORS
+This manual page was written by
+.An Mark Johnston Aq Mt markj@FreeBSD.org .