1.\" 2.\" Copyright (c) 2025 Mateusz Piotrowski <0mp@FreeBSD.org> 3.\" 4.\" SPDX-License-Identifier: BSD-2-Clause 5.\" 6.Dd November 6, 2025 7.Dt DTRACE_PID 4 8.Os 9.Sh NAME 10.Nm dtrace_pid 11.Nd a DTrace provider for dynamic userspace tracing based on function boundary instrumentation 12.Sh SYNOPSIS 13.Nm pid Ns Ar PID Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&:entry 14.\" XXX: For some reason Op renders here in bold, so use literal square 15.\" brackets instead. 16.Nm pid Ns Ar PID Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&: Ns No \&[ Ns Ar offset Ns No \&] 17.Nm pid Ns Ar PID Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&:return 18.Sh DESCRIPTION 19The 20.Nm pid 21provider implements userspace dynamic tracing 22by instrumenting the entry and return of functions in userspace programs. 23Refer to 24.Xr dtrace_fbt 4 25for more details about function boundary instrumentation. 26.Pp 27The 28.Nm pid 29provider provides the following probes: 30.Bl -inset 31.It Nm pid Ns Ar PID Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&:entry 32instruments the entry of the 33.Ar function . 34.It Nm pid Ns Ar PID Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&: Ns Op Ar offset 35instruments the instruction within the 36.Ar function 37located at 38.Ar offset 39bytes (expressed as a hexadecimal integer). 40.It Nm pid Ns Ar PID Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&:return 41instruments the return from the 42.Ar function . 43.El 44.Ss Probe Arguments 45The arguments of the entry probe 46.Pq Nm pid Ns Ar PID Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&:entry 47are the arguments of the traced function call. 48.Bl -column -offset indent "Entry Probe Argument" "Definition" 49.It Sy Entry Probe Argument Ta Sy Definition 50.It Ft uint64_t Fa arg0 Ta Function's first argument 51.It Ft uint64_t Fa arg1 Ta Function's second argument 52.It Ft uint64_t Fa arg2 Ta Function's third argument 53.It Fa ... Ta ... 54.El 55.Pp 56The offset probes 57.Pq Nm pid Ns Ar PID Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&: Ns Op Ar offset 58do not define any arguments. 59Use 60.Va uregs[] 61to inspect the registers. 62.Pp 63The arguments of the return probe 64.Pq Nm pid Ns Ar PID Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&:return 65are the program counter and the function's return value. 66.Bl -column -offset indent "Return Probe Argument" "Definition" 67.It Sy Return Probe Argument Ta Sy Definition 68.It Ft uint64_t Fa arg0 Ta Program counter 69.It Ft uint64_t Fa arg1 Ta Function's return value 70.El 71.Pp 72Note that all probe arguments within the 73.Nm pid 74provider are of type 75.Ft uint64_t . 76.Sh SEE ALSO 77.Xr dtrace 1 , 78.Xr dtrace_fbt 4 , 79.Xr dtrace_kinst 4 , 80.Xr elf 5 , 81.Xr d 7 , 82.Xr tracing 7 83.Rs 84.%A Brendan Gregg 85.%A Jim Mauro 86.%B DTrace: Dynamic Tracing in Oracle Solaris, Mac OS X and FreeBSD 87.%I Prentice Hall 88.%D 2011 89.%U https://www.brendangregg.com/dtracebook/ 90.Re 91.Rs 92.%B The illumos Dynamic Tracing Guide 93.%O Chapter pid Provider 94.%D 2008 95.%U https://illumos.org/books/dtrace/chp-pid.html 96.Re 97.Sh AUTHORS 98This manual page was written by 99.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org . 100