1.\" 2.\" Copyright (c) 2025-2026 Mateusz Piotrowski <0mp@FreeBSD.org> 3.\" 4.\" SPDX-License-Identifier: BSD-2-Clause 5.\" 6.Dd September 19, 2026 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 EXAMPLES 77.Ss Example 1: Listing Program's Function Entries 78The following example lists the entry probes of 79.Xr cat 1 Ap s 80global functions: 81.Bd -literal -offset indent 82# dtrace -l -c cat -n 'pid$target:cat::entry' 83 ID PROVIDER MODULE FUNCTION NAME 84106058 pid34639 cat __do_global_dtors_aux entry 85106059 pid34639 cat usage entry 86106060 pid34639 cat scanfiles entry 87106061 pid34639 cat cook_cat entry 88106062 pid34639 cat __do_global_ctors_aux entry 89106063 pid34639 cat _start entry 90106064 pid34639 cat main entry 91.Ed 92.Pp 93This example will not work without 94.Xr cat 1 95debug symbols. 96.Sh SEE ALSO 97.Xr dtrace 1 , 98.Xr dtrace_fbt 4 , 99.Xr dtrace_kinst 4 , 100.Xr elf 5 , 101.Xr d 7 , 102.Xr tracing 7 103.Rs 104.%A Brendan Gregg 105.%A Jim Mauro 106.%B DTrace: Dynamic Tracing in Oracle Solaris, Mac OS X and FreeBSD 107.%I Prentice Hall 108.%D 2011 109.%U https://www.brendangregg.com/dtracebook/ 110.Re 111.Rs 112.%B The illumos Dynamic Tracing Guide 113.%O Chapter pid Provider 114.%D 2008 115.%U https://illumos.org/books/dtrace/chp-pid.html 116.Re 117.Sh AUTHORS 118This manual page was written by 119.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org . 120