NAME
dtrace_pid – a DTrace provider for dynamic userspace tracing based on function boundary instrumentation
SYNOPSIS
pidPID:module:function:entry
pidPID:module:function:[offset]
pidPID:module:function:return
DESCRIPTION
The pid provider implements userspace dynamic tracing by instrumenting the entry and return of functions in userspace programs. Refer to dtrace_fbt(4) for more details about function boundary instrumentation.
The pid provider provides the following probes:
- pidPID:module:function:entry
-
instruments the entry of the function.
- pidPID:module:function:[offset]
-
instruments the instruction within the function located at offset bytes (expressed as a hexadecimal integer).
- pidPID:module:function:return
-
instruments the return from the function.
Probe Arguments
The arguments of the entry probe (pidPID:module:function:entry) are the arguments of the traced function call.
| Entry Probe Argument | Definition |
| uint64_t arg0 | Function's first argument |
| uint64_t arg1 | Function's second argument |
| uint64_t arg2 | Function's third argument |
| ... | ... |
The offset probes (pidPID:module:function:[offset]) do not define any arguments. Use uregs[] to inspect the registers.
The arguments of the return probe (pidPID:module:function:return) are the program counter and the function's return value.
| Return Probe Argument | Definition |
| uint64_t arg0 | Program counter |
| uint64_t arg1 | Function's return value |
Note that all probe arguments within the pid provider are of type uint64_t.
EXAMPLES
Example 1: Listing Program's Function Entries
The following example lists the entry probes of cat(1)'s global functions:
# dtrace -l -c cat -n 'pid$target:cat::entry'
ID PROVIDER MODULE FUNCTION NAME
106058 pid34639 cat __do_global_dtors_aux entry
106059 pid34639 cat usage entry
106060 pid34639 cat scanfiles entry
106061 pid34639 cat cook_cat entry
106062 pid34639 cat __do_global_ctors_aux entry
106063 pid34639 cat _start entry
106064 pid34639 cat main entry
This example will not work without cat(1) debug symbols.
SEE ALSO
dtrace(1), dtrace_fbt(4), dtrace_kinst(4), elf(5), d(7), tracing(7) Brendan Gregg and Jim Mauro, DTrace: Dynamic Tracing in Oracle Solaris, Mac OS X and FreeBSD, Prentice Hall, 2011, https://www.brendangregg.com/dtracebook/. The illumos Dynamic Tracing Guide, 2008, Chapter pid Provider, https://illumos.org/books/dtrace/chp-pid.html.
AUTHORS
This manual page was written by Mateusz Piotrowski ⟨[email protected]⟩.