---
name: "dtrace_pid"
section: "4"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["freebsd"]
url: "https://new.carta.tech/dtrace_pid"
---

# dtrace\_pid(4)

a DTrace provider for dynamic userspace tracing based on function boundary instrumentation

## NAME

**dtrace\_pid** – a DTrace provider for dynamic userspace tracing based on function boundary instrumentation

## SYNOPSIS

**pid***PID***:***module***:***function***:entry**

**pid***PID***:***module***:***function***:**\[*offset*\]

**pid***PID***:***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)](/dtrace_fbt/4.md) for more details about function boundary instrumentation.

The **pid** provider provides the following probes:

- **pid***PID***:***module***:***function***:entry**

  instruments the entry of the *function*.

- **pid***PID***:***module***:***function***:**\[*offset*\]

  instruments the instruction within the *function* located at *offset* bytes (expressed as a hexadecimal integer).

- **pid***PID***:***module***:***function***:return**

  instruments the return from the *function*.

### Probe Arguments

The arguments of the entry probe (**pid***PID***:***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 (**pid***PID***:***module***:***function***:**\[*offset*\]) do not define any arguments. Use *uregs\[\]* to inspect the registers.

The arguments of the return probe (**pid***PID***:***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)](/cat/1.md)'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)](/cat/1.md) debug symbols.

## SEE ALSO

[dtrace(1)](/dtrace/1.md), [dtrace\_fbt(4)](/dtrace_fbt/4.md), [dtrace\_kinst(4)](/dtrace_kinst/4.md), [elf(5)](/elf/5.md), [d(7)](/d/7.md), [tracing(7)](/tracing/7.md) 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 ⟨*0mp@FreeBSD.org*⟩.