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.
#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 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".
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) |
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.
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 Wordsadd | 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. |
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 attributes probes selector_list list attributes 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. |