'\" te .\" Copyright 1994 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_DECLARE_RECORD 3TNF "Dec 31, 1996" .SH NAME TNF_DECLARE_RECORD, TNF_DEFINE_RECORD_1, TNF_DEFINE_RECORD_2, TNF_DEFINE_RECORD_3, TNF_DEFINE_RECORD_4, TNF_DEFINE_RECORD_5 \- TNF type extension interface for probes .SH SYNOPSIS .LP .nf \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ...[ \fB-ltnfprobe\fR ] [ \fIlibrary\fR ... ] #include \fBTNF_DECLARE_RECORD\fR(\fIc_type\fR, \fItnf_type\fR); .fi .LP .nf \fBTNF_DEFINE_RECORD_1\fR(\fIc_type\fR, \fItnf_type\fR, \fItnf_member_type_1\fR, \fIc_member_name_1\fR); .fi .LP .nf \fBTNF_DEFINE_RECORD_2\fR(\fIc_type\fR, \fItnf_type\fR, \fItnf_member_type_1\fR, \fIc_member_name_1\fR, \fItnf_member_type_2\fR, \fIc_member_name_2\fR); .fi .LP .nf \fBTNF_DEFINE_RECORD_3\fR(\fIc_type\fR, \fItnf_type\fR, \fItnf_member_type_1\fR, \fIc_member_name_1\fR, \fItnf_member_type_2\fR, \fIc_member_name_2\fR, \fItnf_member_type_3\fR, \fIc_member_name_3\fR); .fi .LP .nf \fBTNF_DEFINE_RECORD_4\fR(\fIc_type\fR, \fItnf_type\fR, \fItnf_member_type_1\fR, \fIc_member_name_1\fR, \fItnf_member_type_2\fR, \fIc_member_name_2\fR, \fItnf_member_type_3\fR, \fIc_member_name_3\fR, \fItnf_member_type_4\fR, \fIc_member_name_4\fR); .fi .LP .nf \fBTNF_DEFINE_RECORD_5\fR(\fIc_type\fR, \fItnf_type\fR, \fItnf_member_type_1\fR, \fIc_member_name_1\fR, \fItnf_member_type_2\fR, \fIc_member_name_2\fR, \fItnf_member_type_3\fR, \fIc_member_name_3\fR,\fItnf_member_type_4\fR, \fIc_member_name_4\fR, \fItnf_member_type_5\fR, \fIc_member_name_5\fR); .fi .SH DESCRIPTION .sp .LP This macro interface is used to extend the TNF (Trace Normal Form) types that can be used in \fBTNF_PROBE\fR(3TNF). .sp .LP There should be only one \fBTNF_DECLARE_RECORD\fR and one \fBTNF_DEFINE_RECORD\fR per new type being defined. The \fBTNF_DECLARE_RECORD\fR should precede the \fBTNF_DEFINE_RECORD\fR. It can be in a header file that multiple source files share if those source files need to use the \fItnf_type\fR being defined. The \fBTNF_DEFINE_RECORD\fR should only appear in one of the source files. .sp .LP The \fBTNF_DEFINE_RECORD\fR macro interface defines a function as well as a couple of data structures. Hence, this interface has to be used in a source file (.c or .cc file) at file scope and not inside a function. .sp .LP Note that there is no semicolon after the \fBTNF_DEFINE_RECORD\fR interface. Having one will generate a compiler warning. .sp .LP Compiling with the preprocessor option \fB-DNPROBE\fR or with the preprocessor control statement \fB#define NPROBE\fR ahead of the \fB#include \fR statement, will stop the TNF type extension code from being compiled into the program. .sp .LP The \fIc_type\fR argument must be a C struct type. It is the template from which the new \fItnf_type\fR is being created. Not all elements of the C struct need be provided in the TNF type being defined. .sp .LP The \fItnf_type\fR argument is the name being given to the newly created type. Use of this interface uses the name space prefixed by \fItnf_type\fR. If a new type called "xxx_type" is defined by a library, then the library should not use "xxx_type" as a prefix in any other symbols it defines. The policy on managing the type name space is the same as managing any other name space in a library; that is, prefix any new TNF types by the unique prefix that the rest of the symbols in the library use. This would prevent name space collisions when linking multiple libraries that define new TNF types. For example, if a library \fBlibpalloc.so\fR uses the prefix "pal" for all symbols it defines, then it should also use the prefix "pal" for all new TNF types being defined. .sp .LP The \fItnf_member_type_n\fR argument is the TNF type of the \fIn\fRth provided member of the C structure. .sp .LP The \fItnf_member_name_n\fR argument is the name of the \fIn\fRth provided member of the C structure. .SH EXAMPLES .LP \fBExample 1 \fRDefining and using a TNF type. .sp .LP The following example demonstrates how a new TNF type is defined and used in a probe. This code is assumed to be part of a fictitious library called "libpalloc.so" which uses the prefix "pal" for all it's symbols. .sp .in +2 .nf #include typedef struct pal_header { long size; char * descriptor; struct pal_header *next; } pal_header_t; TNF_DECLARE_RECORD(pal_header_t, pal_tnf_header); TNF_DEFINE_RECORD_2(pal_header_t, pal_tnf_header, tnf_long, size, tnf_string, descriptor) /* * Note: name space prefixed by pal_tnf_header should not * be used by this client anymore. */ void pal_free(pal_header_t *header_p) { int state; TNF_PROBE_2(pal_free_start, "palloc pal_free", "sunw%debug entering pal_free", tnf_long, state_var, state, pal_tnf_header, header_var, header_p); . . . } .fi .in -2 .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 \fBprex\fR(1), \fBtnfdump\fR(1), \fBTNF_PROBE\fR(3TNF), \fBtnf_process_disable\fR(3TNF), \fBattributes\fR(5) .SH NOTES .sp .LP It is possible to make a \fItnf_type\fR definition be recursive or mutually recursive e.g. a structure that uses the "next" field to point to itself (a linked list). If such a structure is sent in to a \fBTNF_PROBE\fR(3TNF), then the entire linked list will be logged to the trace file (until the "next" field is \fINULL\fR). But, if the list is circular, it will result in an infinite loop. To break the recursion, either do not include the "next" field in the \fItnf_type\fR, or define the type of the "next" member as \fBtnf_opaque\fR.