Sun Microsystems, Inc.
spacerspacer
spacer   www.sun.com docs.sun.com | | |  
spacer
black dot
   
A   B   C   D   E   F   G   H   I   J   K   L   M   N   O   P   Q   R   S   T   U   V   W   X   Y   Z
    
 
TNF Library FunctionsTNF_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(3DL). 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 #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 (see cc(1B)), or place the preprocessor 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 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:
 
"XYZ%debug 'entering function A'; XYZ%exception 'no file'; 
XYZ%func_entry; XYZ%color red blue"

consists of 4 units:
Attribute ValueValues that prex matches on
XYZ%debug'entering function A''entering function A'
XYZ%exception'no file''no file'
XYZ%func_entry/.*/(regular expression)
XYZ%colorred bluered <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 following attributes are predefined:

AttributeSemantics
namename of probe
keyskeys of the probe (value is space- separated tokens)
filefile name of the probe
lineline number of the probe
slotsslot names of the probe event (arg_name_n)
objectthe executable or shared object that this probe is in.
debugdistinguishes debug probes from production probes

arg_type_n

 

This is the type of the nth argument. The following are predefined TNF types:

tnf TypeAssociated C type (and semantics)
tnf_intint
tnf_uintunsigned int
tnf_longlong
tnf_ulongunsigned long
tnf_longlonglong long (if implemented in compilation system)
tnf_ulonglongunsigned long long (if implemented in compilation system)
tnf_floatfloat
tnf_doubledouble
tnf_stringchar *
tnf_opaquevoid *

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 multi-threaded 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. tracing3TNF.
 

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 TYPEATTRIBUTE VALUE
AvailabilitySUNWtnfd
MT LevelMT-Safe

SEE ALSO

 

cc(1B), ld(1), prex(1), tnfdump(1), dlopen(3DL), libtnfctl(3TNF), TNF_DECLARE_RECORD(3TNF), threads(3THR), tnf_process_disable(3TNF), tracing(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 environment variable LD_PRELOAD set to libtnfprobe.so.1. See ld(1). If libtnfprobe is explicitly linked into the program, it must be before libthread on the link line.


SunOS 5.9Go To TopLast Changed 4 Mar 1997

 
      
      
Copyright 2002 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.