... 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)|http://docs.sun.com/doc/819-2239/mdb-1?a=view] to display a list of objects:
{noformat}
$ 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
{noformat}
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:
{noformat}
pid123:libc.so.1:strcpy:entry
pid123:libc.so:strcpy:entry
pid123:libc:strcpy:entry
{noformat}
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:
{noformat}
pid123:csh:main:return
pid123:a.out:main:return
{noformat}
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:
{noformat}
# 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
{noformat}
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|User Process Tracing] for examples of how to use the {{pid}} provider effectively.
[Top|#top]
h2. {anchor:CHP-PID-FB} 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.
[Top|#top]
h3. {anchor:CHP-PID-ENTRY} {{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.
[Top|#top]
h3. {anchor:CHP-PID-RETURN} {{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.
[Top|#top]
h2. {anchor:CHP-PID-OFFSETS} 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:
{noformat}
pid123:a.out:main:4
{noformat}
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|User Process Tracing#CHP-USER-UREGS] for more information.
[Top|#top]
h2. {anchor:CHP-PID-STABILITY} 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 [Chapter 39, Stability|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|
{excerpt:hidden=true}Converted by tech dogg's sgml2wiki on Tue 20 Nov 2007 at 9:25:32 PM{excerpt} |