TNF_PROBE(3TNF) TNF Library Functions TNF_PROBE(3TNF)NAME
TNF_PROBE, TNF_PROBE_0, TNF_PROBE_1, TNF_PROBE_2, TNF_PROBE_3,
TNF_PROBE_4, TNF_PROBE_5, TNF_PROBE_0_DEBUG, TNF_PROBE_1_DEBUG,
TNF_PROBE_2_DEBUG, TNF_PROBE_3_DEBUG, TNF_PROBE_4_DEBUG,
TNF_PROBE_5_DEBUG, TNF_DEBUG - probe insertion interface
SYNOPSIS
cc [ flag ... ] [ -DTNF_DEBUG ] file ... [ -ltnfprobe ] [ library ... ]
#include <tnf/probe.h>
TNF_PROBE_0(name, keys, detail);
TNF_PROBE_1(name, keys, detail, arg_type_1, arg_name_1, arg_value_1);
TNF_PROBE_2(name, keys, detail, arg_type_1, arg_name_1, arg_value_1,
arg_type_2, arg_name_2, arg_value_2);
TNF_PROBE_3(name, keys, detail, arg_type_1, arg_name_1,arg_value_1,
arg_type_2, arg_name_2, arg_value_2,
arg_type_3, arg_name_3, arg_value_3);
TNF_PROBE_4(name, keys, detail, arg_type_1, arg_name_1, arg_value_1,
arg_type_2, arg_name_2, arg_value_2,
arg_type_3, arg_name_3, arg_value_3,
arg_type_4, arg_name_4, arg_value_4);
TNF_PROBE_5(name, keys, detail, arg_type_1, arg_name_1, arg_value_1,
arg_type_2, arg_name_2, arg_value_2,
arg_type_3, arg_name_3, arg_value_3,
arg_type_4, arg_name_4, arg_value_4,
arg_type_5, arg_name_5, arg_value_5);
TNF_PROBE_0_DEBUG(name, keys, detail);
TNF_PROBE_1_DEBUG(name, keys, detail, arg_type_1, arg_name_1, arg_value_1);
TNF_PROBE_2_DEBUG(name, keys, detail, arg_type_1, arg_name_1, arg_value_1,
arg_type_2, arg_name_2, arg_value_2);
TNF_PROBE_3_DEBUG(name, keys, detail, arg_type_1, arg_name_1, arg_value_1,
arg_type_2, arg_name_2, arg_value_2,
arg_type_3, arg_name_3, arg_value_3);
TNF_PROBE_4_DEBUG(name, keys, detail, arg_type_1, arg_name_1, arg_value_1,
arg_type_2, arg_name_2, arg_value_2,
arg_type_3, arg_name_3, arg_value_3,
arg_type_4, arg_name_4, arg_value_4);
TNF_PROBE_5_DEBUG(name, keys, detail, arg_type_1, arg_name_1, arg_value_1,
arg_type_2, arg_name_2, arg_value_2,
arg_type_3, arg_name_3, arg_value_3,
arg_type_4, arg_name_4, arg_value_4,
arg_type_5, arg_name_5, arg_value_5);
DESCRIPTION
This macro interface is used to insert probes into C or C++ code for
tracing. See tracing(3TNF) for a discussion of the Solaris tracing
architecture, including example source code that uses it.
You can place probes anywhere in C and C++ programs including .init
sections, .fini sections, multi-threaded code, shared objects, and
shared objects opened by dlopen(3C). Use probes to generate trace data
for performance analysis or to write debugging output to stderr.
Probes are controlled at runtime by prex(1).
The trace data is logged to a trace file in Trace Normal Form ( TNF).
The interface for the user to specify the name and size of the trace
file is described in prex(1). Think of the trace file as the least
recently used circular buffer. Once the file has been filled, newer
events will overwrite the older ones.
Use TNF_PROBE_0 through TNF_PROBE_5 to create production probes. These
probes are compiled in by default. Developers are encouraged to embed
such probes strategically, and to leave them compiled within production
software. Such probes facilitate on-site analysis of the software.
Use TNF_PROBE_0_DEBUG through TNF_PROBE_5_DEBUG to create debug
probes. These probes are compiled out by default. If you compile the
program with the preprocessor option -DTNF_DEBUG or with the pre‐
processor control statement #define TNF_DEBUG ahead of the #include
<tnf/probe.h> statement, the debug probes will be compiled into the
program. When compiled in, debug probes differ in only one way from the
equivalent production probes. They contain an additional "debug"
attribute which may be used to distinguish them from production probes
at runtime, for example, when using prex(). Developers are encouraged
to embed any number of probes for debugging purposes. Disabled probes
have such a small runtime overhead that even large numbers of them do
not make a significant impact.
If you compile with the preprocessor option -DNPROBE or place the pre‐
processor control statement #define NPROBE ahead of the #include
<tnf/probe.h> statement, no probes will be compiled into the program.
name
The name of the probe should follow the syntax guidelines for identi‐
fiers in ANSI C. The use of name declares it, hence no separate decla‐
ration is necessary. This is a block scope declaration, so it does not
affect the name space of the program.
keys
keys is a string of space-separated keywords that specify the groups
that the probe belongs to. Semicolons, single quotation marks, and the
equal character (=) are not allowed in this string. If any of the
groups are enabled, the probe is enabled. keys cannot be a variable.
It must be a string constant.
detail
detail is a string that consists of <attribute> <value> pairs that are
each separated by a semicolon. The first word (up to the space) is
considered to be the attribute and the rest of the string (up to the
semicolon) is considered the value. Single quotation marks are used to
denote a string value. Besides quotation marks, spaces separate multi‐
ple values. The value is optional. Although semicolons or single quota‐
tion marks generally are not allowed within either the attribute or
the value, when text with embedded spaces is meant to denote a single
value, use single quotes surrounding this text.
Use detail for one of two reasons. First, use detail to supply an
attribute that a user can type into prex(1) to select probes. For
example, if a user defines an attribute called color, then prex(1) can
select probes based on the value of color. Second, use detail to anno‐
tate a probe with a string that is written out to a trace file only
once. prex(1) uses spaces to tokenize the value when searching for a
match. Spaces around the semicolon delimiter are allowed. detail cannot
be a variable; it must be a string constant. For example, the detail
string:
"XYZ%debug 'entering function A'; XYZ%exception 'no file';
XYZ%func_entry; XYZ%color red blue"
consists of 4 units:
┌─────────────────────────────────────────────────────────────────────────┐
│ Attribute Value Values that prex matches on │
├─────────────────────────────────────────────────────────────────────────┤
│XYZ%debug 'entering function A' 'entering function A' │
│XYZ%exception 'no file' 'no file' │
│XYZ%func_entry /.*/ (regular expression) │
│XYZ%color red blue red <or> blue │
└─────────────────────────────────────────────────────────────────────────┘
Attribute names must be prefixed by the vendor stock symbol followed by
the '%' character. This avoids conflicts in the attribute name space.
All attributes that do not have a '%' character are reserved. The fol‐
lowing attributes are predefined:
┌───────────────────────────────────────────────────────────┐
│ Attribute Semantics │
├───────────────────────────────────────────────────────────┤
│name name of probe │
│keys keys of the probe (value is │
│ space− separated tokens) │
│file file name of the probe │
│line line number of the probe │
│slots slot names of the probe │
│ event (arg_name_n) │
│object the executable or shared │
│ object that this probe is │
│ in. │
│debug distinguishes debug probes │
│ from production probes │
└───────────────────────────────────────────────────────────┘
arg_type_n
This is the type of the nth argument. The following are predefined
TNF types:
┌────────────────────────────────────────────────────────────────┐
│ tnf Type Associated C type (and semantics) │
├────────────────────────────────────────────────────────────────┤
│tnf_int int │
│tnf_uint unsigned int │
│tnf_long long │
│tnf_ulong unsigned long │
│tnf_longlong long long (if implemented in com‐ │
│ pilation system) │
│tnf_ulonglong unsigned long long (if imple‐ │
│ mented in compilation system) │
│tnf_float float │
│tnf_double double │
│tnf_string char * │
│tnf_opaque void * │
└────────────────────────────────────────────────────────────────┘
To define new TNF types that are records consisting of the predefined
TNF types or references to other user defined types, use the interface
specified in TNF_DECLARE_RECORD(3TNF).
arg_name_n
arg_name_n is the name that the user associates with the nth argument.
Do not place quotation marks around arg_name_n. Follow the syntax
guidelines for identifiers in ANSI C. The string version of arg_name_n
is stored for every probe and can be accessed as the attribute "slots".
arg_value_n
arg_value_n is evaluated to yield a value to be included in the trace
file. A read access is done on any variables that are in mentioned in
arg_value_n. In a multithreaded program, it is the user's responsibil‐
ity to place locks around the TNF_PROBE macro if arg_value_n contains
a variable that should be read protected.
EXAMPLES
Example 1 tracing(3TNF)
See tracing(3TNF) for complete examples showing debug and production
probes in source code.
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Availability │developer/tnf │
├─────────────────────────────┼─────────────────────────────┤
│MT Level │MT-Safe │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOld(1), prex(1), tnfdump(1), dlopen(3C), libtnfctl(3TNF),
TNF_DECLARE_RECORD(3TNF), threads(5), tnf_process_disable(3TNF), trac‐
ing(3TNF), attributes(5)NOTES
If attaching to a running program with prex(1) to control the probes,
compile the program with -ltnfprobe or start the program with the envi‐
ronment variable LD_PRELOAD set to libtnfprobe.so.1. See ld(1). If
libtnfprobe is explicitly linked into the program, it must be listed
before libdoor, which in turn must be listed before libthread on the
link line.
SunOS 5.11 1 Mar 2004 TNF_PROBE(3TNF)
