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 (see cc(1B)), or with the preprocessor control
statement #defineTNF_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 (see cc(1B)),
or place the preprocessor control statement #defineNPROBE 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 identifiers
in ANSI C. The use of name declares it, hence no
separate declaration 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 multiple values. The value is optional. Although semicolons or single
quotation 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 annotate 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:

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 following 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 compilation system)

tnf_ulonglong

unsigned
long long (if implemented 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 responsibility 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.

See Also

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 environment 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.