path: root/usr/src/man/man3tnf/TNF_PROBE.3tnf

'\" te
.\" Copyright 2004. Sun Microsystems Inc.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
.\"  See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with
.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH TNF_PROBE 3TNF "Mar 1, 2004"
.SH 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
.SH SYNOPSIS
.LP
.nf
\fBcc\fR [ \fIflag\fR ... ] [ \fB-DTNF_DEBUG\fR ] \fIfile\fR ... [ \fB-ltnfprobe\fR ] [ \fIlibrary\fR ... ]
#include <tnf/probe.h>

\fBTNF_PROBE_0\fR(\fIname\fR, \fIkeys\fR, \fIdetail\fR);
.fi

.LP
.nf
\fBTNF_PROBE_1\fR(\fIname\fR, \fIkeys\fR, \fIdetail\fR, \fIarg_type_1\fR, \fIarg_name_1\fR, \fIarg_value_1\fR);
.fi

.LP
.nf
\fBTNF_PROBE_2\fR(\fIname\fR, \fIkeys\fR, \fIdetail\fR, \fIarg_type_1\fR, \fIarg_name_1\fR, \fIarg_value_1\fR,
     \fIarg_type_2\fR, \fIarg_name_2\fR, \fIarg_value_2\fR);
.fi

.LP
.nf
\fBTNF_PROBE_3\fR(\fIname\fR, \fIkeys\fR, \fIdetail\fR, \fIarg_type_1\fR, \fIarg_name_1\fR,\fIarg_value_1\fR,
     \fIarg_type_2\fR, \fIarg_name_2\fR, \fIarg_value_2\fR,
     \fIarg_type_3\fR, \fIarg_name_3\fR, \fIarg_value_3\fR);
.fi

.LP
.nf
\fBTNF_PROBE_4\fR(\fIname\fR, \fIkeys\fR, \fIdetail\fR, \fIarg_type_1\fR, \fIarg_name_1\fR, \fIarg_value_1\fR,
     \fIarg_type_2\fR, \fIarg_name_2\fR, \fIarg_value_2\fR,
     \fIarg_type_3\fR, \fIarg_name_3\fR, \fIarg_value_3\fR,
     \fIarg_type_4\fR, \fIarg_name_4\fR, \fIarg_value_4\fR);
.fi

.LP
.nf
\fBTNF_PROBE_5\fR(\fIname\fR, \fIkeys\fR, \fIdetail\fR, \fIarg_type_1\fR, \fIarg_name_1\fR, \fIarg_value_1\fR,
     \fIarg_type_2\fR, \fIarg_name_2\fR, \fIarg_value_2\fR,
     \fIarg_type_3\fR, \fIarg_name_3\fR, \fIarg_value_3\fR,
     \fIarg_type_4\fR, \fIarg_name_4\fR, \fIarg_value_4\fR,
     \fIarg_type_5\fR, \fIarg_name_5\fR, \fIarg_value_5\fR);
.fi

.LP
.nf
\fBTNF_PROBE_0_DEBUG\fR(\fIname\fR, \fIkeys\fR, \fIdetail\fR);
.fi

.LP
.nf
\fBTNF_PROBE_1_DEBUG\fR(\fIname\fR, \fIkeys\fR, \fIdetail\fR, \fIarg_type_1\fR, \fIarg_name_1\fR, \fIarg_value_1\fR);
.fi

.LP
.nf
\fBTNF_PROBE_2_DEBUG\fR(\fIname\fR, \fIkeys\fR, \fIdetail\fR, \fIarg_type_1\fR, \fIarg_name_1\fR, \fIarg_value_1\fR,
     \fIarg_type_2\fR, \fIarg_name_2\fR, \fIarg_value_2\fR);
.fi

.LP
.nf
\fBTNF_PROBE_3_DEBUG\fR(\fIname\fR, \fIkeys\fR, \fIdetail\fR, \fIarg_type_1\fR, \fIarg_name_1\fR, \fIarg_value_1\fR,
     \fIarg_type_2\fR, \fIarg_name_2\fR, \fIarg_value_2\fR,
     \fIarg_type_3\fR, \fIarg_name_3\fR, \fIarg_value_3\fR);
.fi

.LP
.nf
\fBTNF_PROBE_4_DEBUG\fR(\fIname\fR, \fIkeys\fR, \fIdetail\fR, \fIarg_type_1\fR, \fIarg_name_1\fR, \fIarg_value_1\fR,
     \fIarg_type_2\fR, \fIarg_name_2\fR, \fIarg_value_2\fR,
     \fIarg_type_3\fR, \fIarg_name_3\fR, \fIarg_value_3\fR,
     \fIarg_type_4\fR, \fIarg_name_4\fR, \fIarg_value_4\fR);
.fi

.LP
.nf
\fBTNF_PROBE_5_DEBUG\fR(\fIname\fR, \fIkeys\fR, \fIdetail\fR, \fIarg_type_1\fR, \fIarg_name_1\fR, \fIarg_value_1\fR,
     \fIarg_type_2\fR, \fIarg_name_2\fR, \fIarg_value_2\fR,
     \fIarg_type_3\fR, \fIarg_name_3\fR, \fIarg_value_3\fR,
     \fIarg_type_4\fR, \fIarg_name_4\fR, \fIarg_value_4\fR,
     \fIarg_type_5\fR, \fIarg_name_5\fR, \fIarg_value_5\fR);
.fi

.SH DESCRIPTION
.sp
.LP
This macro interface is used to insert probes into C or C++ code for tracing.
See \fBtracing\fR(3TNF) for a discussion of the Solaris tracing architecture,
including example source code that uses it.
.sp
.LP
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 \fBdlopen\fR(3C). Use probes to  generate trace data for performance
analysis or to write debugging output to stderr.  Probes are controlled at
runtime by \fBprex\fR(1).
.sp
.LP
The trace data is logged to a trace file in Trace Normal Form  ( \fBTNF).\fR
The interface for the user to specify the name and size of the trace file is
described in  \fBprex\fR(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.
.sp
.LP
Use \fBTNF_PROBE_0\fR through  \fBTNF_PROBE_5\fR 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.
.sp
.LP
Use \fBTNF_PROBE_0_DEBUG\fR through  \fBTNF_PROBE_5_DEBUG\fR to create debug
probes. These probes are compiled out by default. If you compile the program
with the preprocessor option  \fB-DTNF_DEBUG\fR or with the preprocessor
control statement  \fB#define\fR \fBTNF_DEBUG\fR ahead of the  \fB#include\fR
\fB<tnf/probe.h>\fR 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 \fBprex()\fR. 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.
.sp
.LP
If you compile with the preprocessor option  \fB-DNPROBE\fR or place the
preprocessor control statement  \fB#define\fR \fBNPROBE\fR ahead of the
\fB#include\fR \fB<tnf/probe.h>\fR statement, no probes will be compiled into
the program.
.SS "name"
.sp
.LP
The \fIname\fR of the probe should follow the syntax guidelines for identifiers
in ANSI C. The use of \fIname\fR 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.
.SS "keys"
.sp
.LP
\fIkeys\fR 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. \fIkeys\fR cannot be a variable. It must be a string
constant.
.SS "detail"
.sp
.LP
\fIdetail\fR 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.
.sp
.LP
Use  \fIdetail\fR for one of two reasons.  First, use  \fIdetail\fR to supply
an attribute that a user can type into  \fBprex\fR(1) to select probes. For
example, if a user defines an attribute called color, then  \fBprex\fR(1) can
select probes based on the value of color. Second, use \fIdetail\fR to annotate
a probe with a string that is written out to a trace file only once.
\fBprex\fR(1) uses spaces to tokenize the value when searching for a match.
Spaces around the semicolon delimiter are allowed. \fIdetail\fR cannot be a
variable; it must be a string constant. For example, the  \fIdetail\fR string:
.sp
.in +2
.nf
"XYZ%debug 'entering function A'; XYZ%exception 'no file';
XYZ%func_entry; XYZ%color red blue"
.fi
.in -2

.sp
.LP
consists of 4 units:
.sp

.sp
.TS
box;
c c c
l l l .
\fBAttribute\fR	\fBValue\fR	\fBValues that\fR \fBprex\fR \fBmatches on\fR
_
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
.TE

.sp
.LP
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:
.sp

.sp
.TS
box;
c c
l l .
\fBAttribute\fR	\fBSemantics\fR
_
name	name of probe
keys	T{
keys of the probe (value is space\(mi separated tokens)
T}
file	file name of the probe
line	line number of the probe
slots	T{
slot names of the probe event (\fIarg_name_n\fR)
T}
object	T{
the executable or shared object that this probe is in.
T}
debug	T{
distinguishes debug probes from production probes
T}
.TE

.SS "arg_type_n"
.sp
.LP
This is the type of the  \fIn\fRth argument. The following are predefined
\fBTNF\fR types:
.sp

.sp
.TS
box;
c c
l l .
\fBtnf Type\fR	\fBAssociated C type (and semantics)\fR
_
tnf_int	int
tnf_uint	unsigned int
tnf_long	long
tnf_ulong	unsigned long
tnf_longlong	T{
long long (if implemented in compilation system)
T}
tnf_ulonglong	T{
unsigned long long (if implemented in compilation system)
T}
tnf_float	float
tnf_double	double
tnf_string	char *
tnf_opaque	void *
.TE

.sp
.LP
To define new  \fBTNF\fR types that are records consisting of the predefined
\fBTNF\fR types or references to other user defined types, use the interface
specified  in  \fBTNF_DECLARE_RECORD\fR(3TNF).
.SS "arg_name_n"
.sp
.LP
\fIarg_name_n\fR is the name that the user associates with the  \fIn\fRth
argument. Do not place quotation marks around \fIarg_name_n\fR. Follow the
syntax guidelines for identifiers in ANSI C. The string version of
\fIarg_name_n\fR is stored for every probe and can be accessed as the attribute
"slots".
.SS "arg_value_n"
.sp
.LP
\fIarg_value_n\fR 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
\fIarg_value_n\fR. In a multithreaded program, it is the user's responsibility
to place locks around the \fBTNF_PROBE\fR macro if  \fIarg_value_n\fR contains
a variable that should be read protected.
.SH EXAMPLES
.LP
\fBExample 1 \fRtracing(3TNF)
.sp
.LP
See \fBtracing\fR(3TNF) for complete examples showing debug and production
probes in source code.

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
MT Level	MT-Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBld\fR(1), \fBprex\fR(1), \fBtnfdump\fR(1), \fBdlopen\fR(3C),
\fBlibtnfctl\fR(3TNF), \fBTNF_DECLARE_RECORD\fR(3TNF), \fBthreads\fR(5),
\fBtnf_process_disable\fR(3TNF), \fBtracing\fR(3TNF), \fBattributes\fR(5)
.SH NOTES
.sp
.LP
If attaching to a running program with \fBprex\fR(1) to control the probes,
compile the program with \fB-ltnfprobe\fR or start the program with the
environment variable  \fBLD_PRELOAD\fR set to  \fBlibtnfprobe.so.1\fR. See
\fBld\fR(1). If \fBlibtnfprobe\fR is explicitly linked into the program, it
must be listed before \fBlibdoor\fR, which in turn must be listed before
\fBlibthread\fR on the link line.