pid Provider

Skip to end of metadata
Go to start of metadata

pid Provider

The pid provider allows for tracing of the entry and return of any 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. Use one of the following methods to compile a particular C function so that it will not be inlined.
  • Sun Studio: #pragma no_inline (funcname[, funcname])
  • gcc: funcname __attribute__ ((noinline))
    Consult your compiler documentation for updates.


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: [ ]
> ::objects
   10000    34000    24000 /usr/bin/csh
ff3c0000 ff3e8000    28000 /lib/
ff350000 ff37a000    2a000 /lib/
ff200000 ff2be000    be000 /lib/
ff3a0000 ff3a2000     2000 /lib/
ff320000 ff324000     4000 /platform/sun4u/lib/

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:

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:


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 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); }'

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 Solaris release.

See Chapter 33, User Process Tracing for examples of how to use the pid provider effectively.


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.


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.


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.


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:


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.



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 Chapter 39, 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
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Feb 23, 2009

    I believe the following should be added to the top of this page, per CR 6480235:

    When the compiler inlines a function, the pid provider's probe does not fire. Use one of the following methods to compile a particular C function so that it will not be inlined.
    • Sun Studio: #pragma no_inline (funcname[, funcname])
    • gcc: <function name> __attribute__ ((noinline))
      Consult your compiler documentation for updates.

    I believe the following note also needs to be added to this page:

    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.
    1. Feb 23, 2009

      Hey Alta,

      The first note sounds perfect. Can you explain a bit more about the second note?

      1. Feb 23, 2009

        The second note is in the Solaris 10 version:

        This seems to be the fix for this change request:

        This CR is just a bit over a year old and was fixed in the Solaris 10 version just a couple of months ago. Is this a correct fix? Does it apply to this wiki version as well?

        Two workarounds are listed in the CR. Should they be documented?

Sign up or Log in to add a comment or watch this page.

The individuals who post here are part of the extended Oracle community and they might not be employed or in any way formally affiliated with Oracle. The opinions expressed here are their own, are not necessarily reviewed in advance by anyone but the individual authors, and neither Oracle nor any other party necessarily agrees with them.