Page MenuHomeFreeBSD
Files F156921934

D51287.id158411.diff
No OneTemporary
Actions

D51287.id158411.diff
View Options

diff --git a/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 b/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1
--- a/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1
+++ b/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1
@@ -20,7 +20,7 @@
.\"
.\" $FreeBSD$
.\"
-.Dd July 12, 2025
+.Dd July 13, 2025
.Dt DTRACE 1
.Os
.Sh NAME
@@ -1227,6 +1227,7 @@
.Xr dtrace_ip 4 ,
.Xr dtrace_kinst 4 ,
.Xr dtrace_lockstat 4 ,
+.Xr dtrace_pid 4 ,
.Xr dtrace_proc 4 ,
.Xr dtrace_sched 4 ,
.Xr dtrace_sctp 4 ,
diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile
--- a/share/man/man4/Makefile
+++ b/share/man/man4/Makefile
@@ -984,6 +984,7 @@
dtrace_ip.4 \
dtrace_kinst.4 \
dtrace_lockstat.4 \
+ dtrace_pid.4 \
dtrace_proc.4 \
dtrace_sched.4 \
dtrace_sctp.4 \
diff --git a/share/man/man4/dtrace_pid.4 b/share/man/man4/dtrace_pid.4
new file mode 100644
--- /dev/null
+++ b/share/man/man4/dtrace_pid.4
@@ -0,0 +1,103 @@
+.\"
+.\" SPDX-License-Identifier: BSD-2-Clause
+.\"
+.\" Copyright (c) 2025 Mateusz Piotrowski <0mp@FreeBSD.org>
+.\"
+.Dd July 13, 2025
+.Dt DTRACE_PID 4
+.Os
+.Sh NAME
+.Nm dtrace_pid
+.Nd a DTrace provider for dynamic userspace tracing based on function boundaries
+.Sh SYNOPSIS
+.Nm pid Ns Ar PID Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&:entry
+.\" XXX: For some reason Op renders here in bold, so use literal square
+.\" brackets instead.
+.Nm pid Ns Ar PID Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&: Ns No \&[ Ns Ar offset Ns No \&]
+.Nm pid Ns Ar PID Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&:return
+.Sh DESCRIPTION
+The
+.Nm pid
+provider instruments the entry and return of functions
+corresponding to an
+.Xr elf 5
+symbol in the userspace programs.
+.Pp
+.Bl -tag
+.It Nm pid Ns Ar PID Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&:entry
+instruments the entry of the
+.Ar function .
+.It Nm pid Ns Ar PID Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&: Ns Op Ar offset
+instruments the instruction within the
+.Ar function
+located at
+.Ar offset
+bytes (expressed as a hexadecimal integer).
+.It Nm pid Ns Ar PID Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&:return
+instruments the return from the
+.Ar function .
+.El
+.Ss Function Boundary Instrumentation
+Refer to
+.Xr dtrace_fbt 4
+for more details.
+The description of function boundary instrumentation there
+applies to
+.Nm pid
+provider's
+userspace dynamic tracing as well.
+.Ss Probe Arguments
+The arguments of the entry probe
+.Pq Nm pid Ns Ar PID Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&:entry
+are the arguments of the traced function call.
+.Bl -column -offset indent "Entry Probe Argument" "Definition"
+.It Sy Entry Probe Argument Ta Sy Definition
+.It Ft uint64_t Fa arg0 Ta Function's first argument
+.It Ft uint64_t Fa arg1 Ta Function's second argument
+.It Ft uint64_t Fa arg2 Ta Function's third argument
+.It Fa ... Ta ...
+.El
+.Pp
+The offset probes
+.Pq Nm pid Ns Ar PID Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&: Ns Op Ar offset
+do not define any arguments.
+Use
+.Va uregs[]
+to inspect the registers.
+.Pp
+The arguments of the return probe
+.Pq Nm pid Ns Ar PID Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&:return
+are the program counter and the function's return value.
+.Pp
+.Bl -column -offset indent "Return Probe Argument" "Definition"
+.It Sy Return Probe Argument Ta Sy Definition
+.It Ft uint64_t Fa arg0 Ta Program counter
+.It Ft uint64_t Fa arg1 Ta Function's return value
+.El
+.Pp
+Note that all probe arguments within the
+.Nm pid
+provider are of type
+.Ft uint64_t .
+.Sh SEE ALSO
+.Xr dtrace 1 ,
+.Xr dtrace_fbt 4 ,
+.Xr dtrace_kinst 4 ,
+.Xr tracing 7
+.Rs
+.%A Brendan Gregg
+.%A Jim Mauro
+.%B DTrace: Dynamic Tracing in Oracle Solaris, Mac OS X and FreeBSD
+.%I Prentice Hall
+.%D 2011
+.%U https://www.brendangregg.com/dtracebook/
+.Re
+.Rs
+.%B The illumos Dynamic Tracing Guide
+.%O Chapter pid Provider
+.%D 2008
+.%U https://illumos.org/books/dtrace/chp-pid.html
+.Re
+.Sh AUTHORS
+This manual page was written by
+.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org .

File Metadata

Mime Type
text/plain
Expires
Mon, May 18, 9:20 AM (4 h, 34 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
33241769
Default Alt Text
D51287.id158411.diff (4 KB)

Event Timeline