pid Provider
The pid
provider allows for tracing of the entry
and return of a function in a user process as well as any instruction as specified
by an absolute address or function offset. The pid
provider
has no probe effect when probes are not enabled. When probes are enabled,
the probes only induce probe effect on those processes that are traced.
When the compiler inlines a function, the pid
provider's
probe does not fire. To avoid inlining a function at compile time, consult
the documentation for your compiler.
The pid
provider behaves unpredictably when
it probes a function that uses function pointers to call a sub-function. You
can explicitly place probes at the addresses of the function's entry and return
to analyze such functions.
30.1. Naming pid Probes
The pid
provider actually defines a class of providers. Each process can potentially have its own associated pid
provider. A process with ID 123, for example, would be traced
by using the pid123
provider. For probes from one of these
providers, the module portion of the probe description refers to an object
loaded in the corresponding process's address space. The following example
uses mdb(1) to display
a list of objects:
$ mdb -p 1234 Loading modules: [ ld.so.1 libc.so.1 ] > ::objects BASE LIMIT SIZE NAME 10000 34000 24000 /usr/bin/csh ff3c0000 ff3e8000 28000 /lib/ld.so.1 ff350000 ff37a000 2a000 /lib/libcurses.so.1 ff200000 ff2be000 be000 /lib/libc.so.1 ff3a0000 ff3a2000 2000 /lib/libdl.so.1 ff320000 ff324000 4000 /platform/sun4u/lib/libc_psr.so.1
In the probe description, you name the object by the name of the file,
not its full path name. You can also omit the .1
or so.1
suffix. All of the following examples name the same probe:
pid123:libc.so.1:strcpy:entry
pid123:libc.so:strcpy:entry
pid123:libc:strcpy:entry
The first example is the actual name of the probe. The other examples are convenient aliases that are replaced with the full load object name internally.
For the load object of the executable, you can use the alias a.out
. The following two probe descriptions name the same probe:
pid123:csh:main:return
pid123:a.out:main:return
As with all anchored DTrace probes, the function field of the probe description names
a function in the
module field. A user application binary might have several names for the same
function. For example, mutex_lock
might be an alternate
name for the function pthread_mutex_lock
in libc.so.1
. DTrace chooses one canonical name for such functions and uses
that name internally. The following example shows how DTrace internally remaps
module and function names to a canonical form:
# dtrace -q -n pid101267:libc:mutex_lock:entry'{ \ printf("%s:%s:%s:%s\n", probeprov, probemod, probefunc, probename); }' pid101267:libc.so.1:pthread_mutex_lock:entry ^C
This automatic renaming means that the names of the probes you enable may be slightly different than those actually enabled. The canonical name will always be consistent between runs of DTrace on systems running the same illumos release.
See User Process Tracing for
examples of how to use the pid
provider effectively.
30.2. Function Boundary Probes
The pid
provider
enables you to trace function entry and return in user programs just as the FBT provider
provides that capability for the kernel. Most of the
examples in this manual that use the FBT provider to trace
kernel function calls can be modified slightly to apply to user processes.
30.2.1. entry Probes
An entry
probe fires when the traced function
is invoked. The arguments to entry probes are the values of the arguments
to the traced function.
30.2.2. return Probes
A return
probes fires when the traced function
returns or makes a tail call to another function. The value for arg0
is
the offset in the function of the return instruction; arg1
holds
the return value.
Using arg
N returns
the raw unfiltered values as type int64_t
. The pid
provider
does not support the args[
N]
format.
30.3. Function Offset Probes
The pid
provider lets you trace any instruction in a function. For example
to trace the instruction 4 bytes into a function main
,
you could use a command similar to the following example:
pid123:a.out:main:4
Every time the program executes the instruction at address main+4
,
this probe will be activated. The arguments for offset probes are undefined.
The uregs[]
array will help you examine process state at
these probe sites. See uregs[] Array for
more information.
30.4. Stability
The pid
provider uses DTrace's stability mechanism
to describe its stabilities, as shown in the following table. For more information
about the stability mechanism, see Stability.
Element |
Name stability |
Data stability |
Dependency class |
---|---|---|---|
Provider |
Evolving |
Evolving |
ISA |
Module |
Private |
Private |
Unknown |
Function |
Private |
Private |
Unknown |
Name |
Evolving |
Evolving |
ISA |
Arguments |
Private |
Private |
Unknown |