Programming Utilities Guide

Components of the `prex` Command

The programmer who has inserted the probe points in the source code has assigned various attributes and (optional) values to each probe point. For example, each probe point has a "name" attribute whose value is the name the programmer chose for it.

Look at Table 1-3 for a list of the predefined attributes and the meanings of their values. The prex command lets you select a group of probe points by matching on their attributes or values. You can then trace or debug the selected probe points.

Table 1-5 lists the prex commands and their actions.

In code Example 1-1, the TNF_PROBE macro defines the probe point named work_start. This probe point has two arguments whose values will be logged--state and message. Each time the probe named work_start is encountered, a time stamp and the values of the variables state and message are logged to the trace file.

Example 1-1 `prex` Attributes and Values

	#include <tnf/probe.h>
	
	int
	work(int state, char *message)
	{
    TNF_PROBE_2(work_start, "work_module work"
               "sunw%debug in function work",
               tnf_long, int_input, state,
               tnf_string, string_input, message);
   ...
   ...
	}

For more information on TNF_PROBE macros, including this example, see "Using the TNF_PROBE Macros".

Table 1-3 lists the predefined attributes.

Attributes

Attributes are characteristics by which you identify probe points in your code. Table 1-3 lists the predefined attributes. You can add more attributes with the TNF_PROBE macros. See "Using the TNF_PROBE Macros".

Table 1-3 Predefined Attributes


Attribute	Characteristics	Value
`enable`	A probe point performs the action that it is set up for only if it is enabled. For example, even when the tracing state is set, tracing occurs only if the probe point has been enabled.	OFF (default)
`file`	The name of the file containing the probe point.	`work.c`
`funcs`	Shows the list of probe functions connected to this probe. Currently, only the debug function is available.	<no value> (default)
`keys`	The groups to which the probe point belongs. If any key in a probe point is enabled, then that probe point is enabled.	work_module work
`line`	The line number in the code on which the probe point occurs.	10
`name`	The name of the probe point.	work_start
`object`	The name of the shared object or executable that the probe is in. Useful for selecting all the probes in a particular module.	work
`slots`	The names of the probe point arguments (arg_name_n), see page 41.	int_input string_input
`trace`	When tracing for a probe point is on, a line is written to the trace file each time the probe point is executed in your program.	ON (default)

Grammar for Matching Probes

Select probes based on their attributes and values. The selection specification is called a selector_list. Each attribute or value can be described as one of the following:

Identifier--a sequence of characters using letters, numbers, and the symbols _\. and % (underscore, backslash, period, and percent). Identifiers cannot begin with a number.

Quoted string--a sequence of characters in single quotes, taken literally; useful when the string being matched is a reserved word. See Table 1-4 for a list of reserved words.

Regular expressions--a sequence of characters enclosed in slashes (//); expanded for a match following the rules for ed(1); when slashes occur in the regular expression, as in a path name, escape the slashes with backslashes: /\/tmp\/filename.

A selector_list consists of one or more selector= selector items. If the initial selector= is not provided, it defaults to keys=. For example, the enable command is specified as :

enable selector_list

An example of this command is:

enable name=/first/ file='sampleZ.c'

This enables all probe points with either the name attribute containing the value first (a regular expression match), or the file attribute equal to the value sampleZ.c (Note that the trace is a disjunction and not a conjunction.)

Use $set_name as a shorthand alias for a selector_list specification. In the following example, the set_name is myprobes.

create $myprobes name=/first/ file='sampleZ.c'
enable $myprobes

This does the same thing as the previous example. The set_name follows the identifier naming rules. The $all default set selects all probes in the program.

Reserved Words

Table 1-4 lists the reserved words. Enclose them in single quotes if you use them to select attributes or values.

Table 1-4 Reserved Words


`add`	`alloc`	`buffer`
`clear`	`connect`	`continue`
`create`	`dealloc`	`delete`
`disable`	`enable`	`fcns`
`filter`	`help`	`history`
`kill`	`ktrace`	`list`
`off`	`on`	`pfilter`
`probes`	`quit`	`resume`
`sets`	`source`	`suspend`
`trace`	`untrace`	`values`

For example:

enable 'trace'='on'

means enable all probes whose trace attribute has the value of ON. Both trace and on are reserved words, so they both have to be enclosed in single quotation marks.

Table 1-5 prex Commands


Command	Action
`clear $set_name` `clear` `selector_list`	Disconnect connected probe functions.
`clear $set_name` `clear` `selector_list`	Disconnect connected probe functions.
`connect &debug $set_name` `connect &debug` `selector_list`	Connect the debug function to the probe points. This does not enable the probe points. The debug function sends its output to `stderr` and not to the trace file.

`continue`	Resume execution of your program, leaving `prex` attached.
`create` `$set_name` `selector_list`	Create a set with probe points matching `selector_list`. Also creates an alias, $`set_name`, for the `selector_list`.
`enable $set_name` `enable` `selector_list` `disable $set_name` `disable` `selector_list`	Control whether the probe points perform the action they are set up for. Probe points are disabled by default; `prex` does not turn on tracing. The cheapest way (in terms of execution time at the probe point) to stop a probe point from tracing is to use the `disable` command. The `enable` and `disable` commands are a master switch. If a probe point is not enabled, even if the probe point is connected to the `debug()` function and `trace` is on, no information is sent to `stderr` or to the trace file.



`help`	List all available `prex` commands.
`list` `attribute`s `probes` `selector_list` `list` `attribute`s `probes $set_name`	List whether specified probe points are enabled or disabled, whether they have tracing on or off, and what the connected probe function is. Attributes are selectors as described in "Attributes ". For example, list name file probes $all lists only `name` and `file` values for matching probe points, while the command `list probes $all` lists all default attributes and their values (`name`, `enable`, `trace`, `file`, `line`, and `funcs`).

`list fcns`	List the defined functions (currently, only `&debug` is defined).
`list history`	List the control command history. The history of the commands used with `connect`, `clear`, `trace`, `untrace`, `enable`, and `disable` are executed whenever a new shared object is brought into your program through `dlopen()`. See "`dlopen()` and `dlclose()` and History".
`list sets`	List the defined sets.
`list values` `attributes`	List the unique values associated with the specified attributes. For example, `list values keys` lists all the unique keys in the program.
`source` `filename`	Source a file of `prex` commands. `filename` is a quoted string.
`trace $set_name` >`trace` `selector_list` `untrace $set_name` `untrace` `selector_list`	Control the tracing action of the probe points. `trace` and `untrace` determine whether a probe point generates a trace record when it is executed. Neither `trace` nor `untrace` enables the probe points. The default mode is that tracing is on. The `untrace` command is useful when you are interested in getting only debug output. If you are using this, your probe should be enabled with tracing off and debug on. Tracing disturbs your program less than the debug function does because `trace` writes to an `mmap`'d file while `debug` writes to `stderr`.



`quit`	Quit `prex`; if your program was loaded with `prex`, it will be killed; if your program was attached to `prex`, it will be resumed.
`quit kill`	Quit `prex` and kill your program.
`quit resume`	Quit `prex` and resume execution of your program.
`quit suspend`	Quit `prex` and leave your program suspended.

Components of the prex Command

Example 1-1 prex Attributes and Values

Attributes

Grammar for Matching Probes

Reserved Words

Components of the `prex` Command

Example 1-1 `prex` Attributes and Values