diff options
Diffstat (limited to 'usr/src/man/man3tnf')
| -rw-r--r-- | usr/src/man/man3tnf/Makefile | 124 | ||||
| -rw-r--r-- | usr/src/man/man3tnf/TNF_DECLARE_RECORD.3tnf | 180 | ||||
| -rw-r--r-- | usr/src/man/man3tnf/TNF_PROBE.3tnf | 332 | ||||
| -rw-r--r-- | usr/src/man/man3tnf/libtnfctl.3tnf | 472 | ||||
| -rw-r--r-- | usr/src/man/man3tnf/tnf_process_disable.3tnf | 119 | ||||
| -rw-r--r-- | usr/src/man/man3tnf/tnfctl_buffer_alloc.3tnf | 207 | ||||
| -rw-r--r-- | usr/src/man/man3tnf/tnfctl_close.3tnf | 129 | ||||
| -rw-r--r-- | usr/src/man/man3tnf/tnfctl_indirect_open.3tnf | 210 | ||||
| -rw-r--r-- | usr/src/man/man3tnf/tnfctl_internal_open.3tnf | 126 | ||||
| -rw-r--r-- | usr/src/man/man3tnf/tnfctl_kernel_open.3tnf | 117 | ||||
| -rw-r--r-- | usr/src/man/man3tnf/tnfctl_pid_open.3tnf | 499 | ||||
| -rw-r--r-- | usr/src/man/man3tnf/tnfctl_probe_apply.3tnf | 229 | ||||
| -rw-r--r-- | usr/src/man/man3tnf/tnfctl_probe_state_get.3tnf | 360 | ||||
| -rw-r--r-- | usr/src/man/man3tnf/tnfctl_register_funcs.3tnf | 86 | ||||
| -rw-r--r-- | usr/src/man/man3tnf/tnfctl_strerror.3tnf | 54 | ||||
| -rw-r--r-- | usr/src/man/man3tnf/tnfctl_trace_attrs_get.3tnf | 184 | ||||
| -rw-r--r-- | usr/src/man/man3tnf/tnfctl_trace_state_set.3tnf | 277 | ||||
| -rw-r--r-- | usr/src/man/man3tnf/tracing.3tnf | 313 |
18 files changed, 0 insertions, 4018 deletions
diff --git a/usr/src/man/man3tnf/Makefile b/usr/src/man/man3tnf/Makefile deleted file mode 100644 index d56a657acb..0000000000 --- a/usr/src/man/man3tnf/Makefile +++ /dev/null @@ -1,124 +0,0 @@ -# -# This file and its contents are supplied under the terms of the -# Common Development and Distribution License ("CDDL"), version 1.0. -# You may only use this file in accordance with the terms of version -# 1.0 of the CDDL. -# -# A full copy of the text of the CDDL should have accompanied this -# source. A copy of the CDDL is also available via the Internet -# at http://www.illumos.org/license/CDDL. -# - -# -# Copyright 2011, Richard Lowe -# Copyright 2013 Nexenta Systems, Inc. All rights reserved. -# - -include $(SRC)/Makefile.master - -MANSECT= 3tnf - -MANFILES= TNF_DECLARE_RECORD.3tnf \ - TNF_PROBE.3tnf \ - libtnfctl.3tnf \ - tnf_process_disable.3tnf \ - tnfctl_buffer_alloc.3tnf \ - tnfctl_close.3tnf \ - tnfctl_indirect_open.3tnf \ - tnfctl_internal_open.3tnf \ - tnfctl_kernel_open.3tnf \ - tnfctl_pid_open.3tnf \ - tnfctl_probe_apply.3tnf \ - tnfctl_probe_state_get.3tnf \ - tnfctl_register_funcs.3tnf \ - tnfctl_strerror.3tnf \ - tnfctl_trace_attrs_get.3tnf \ - tnfctl_trace_state_set.3tnf \ - tracing.3tnf - -MANLINKS= TNF_DEBUG.3tnf \ - TNF_DEFINE_RECORD_1.3tnf \ - TNF_DEFINE_RECORD_2.3tnf \ - TNF_DEFINE_RECORD_3.3tnf \ - TNF_DEFINE_RECORD_4.3tnf \ - TNF_DEFINE_RECORD_5.3tnf \ - TNF_PROBE_0.3tnf \ - TNF_PROBE_0_DEBUG.3tnf \ - TNF_PROBE_1.3tnf \ - TNF_PROBE_1_DEBUG.3tnf \ - TNF_PROBE_2.3tnf \ - TNF_PROBE_2_DEBUG.3tnf \ - TNF_PROBE_3.3tnf \ - TNF_PROBE_3_DEBUG.3tnf \ - TNF_PROBE_4.3tnf \ - TNF_PROBE_4_DEBUG.3tnf \ - TNF_PROBE_5.3tnf \ - TNF_PROBE_5_DEBUG.3tnf \ - tnf_process_enable.3tnf \ - tnf_thread_disable.3tnf \ - tnf_thread_enable.3tnf \ - tnfctl_buffer_dealloc.3tnf \ - tnfctl_check_libs.3tnf \ - tnfctl_continue.3tnf \ - tnfctl_exec_open.3tnf \ - tnfctl_filter_list_add.3tnf \ - tnfctl_filter_list_delete.3tnf \ - tnfctl_filter_list_get.3tnf \ - tnfctl_filter_state_set.3tnf \ - tnfctl_probe_apply_ids.3tnf \ - tnfctl_probe_connect.3tnf \ - tnfctl_probe_disable.3tnf \ - tnfctl_probe_disconnect_all.3tnf \ - tnfctl_probe_enable.3tnf \ - tnfctl_probe_trace.3tnf \ - tnfctl_probe_untrace.3tnf - -TNF_DEFINE_RECORD_1.3tnf := LINKSRC = TNF_DECLARE_RECORD.3tnf -TNF_DEFINE_RECORD_2.3tnf := LINKSRC = TNF_DECLARE_RECORD.3tnf -TNF_DEFINE_RECORD_3.3tnf := LINKSRC = TNF_DECLARE_RECORD.3tnf -TNF_DEFINE_RECORD_4.3tnf := LINKSRC = TNF_DECLARE_RECORD.3tnf -TNF_DEFINE_RECORD_5.3tnf := LINKSRC = TNF_DECLARE_RECORD.3tnf - -TNF_DEBUG.3tnf := LINKSRC = TNF_PROBE.3tnf -TNF_PROBE_0.3tnf := LINKSRC = TNF_PROBE.3tnf -TNF_PROBE_0_DEBUG.3tnf := LINKSRC = TNF_PROBE.3tnf -TNF_PROBE_1.3tnf := LINKSRC = TNF_PROBE.3tnf -TNF_PROBE_1_DEBUG.3tnf := LINKSRC = TNF_PROBE.3tnf -TNF_PROBE_2.3tnf := LINKSRC = TNF_PROBE.3tnf -TNF_PROBE_2_DEBUG.3tnf := LINKSRC = TNF_PROBE.3tnf -TNF_PROBE_3.3tnf := LINKSRC = TNF_PROBE.3tnf -TNF_PROBE_3_DEBUG.3tnf := LINKSRC = TNF_PROBE.3tnf -TNF_PROBE_4.3tnf := LINKSRC = TNF_PROBE.3tnf -TNF_PROBE_4_DEBUG.3tnf := LINKSRC = TNF_PROBE.3tnf -TNF_PROBE_5.3tnf := LINKSRC = TNF_PROBE.3tnf -TNF_PROBE_5_DEBUG.3tnf := LINKSRC = TNF_PROBE.3tnf - -tnf_process_enable.3tnf := LINKSRC = tnf_process_disable.3tnf -tnf_thread_disable.3tnf := LINKSRC = tnf_process_disable.3tnf -tnf_thread_enable.3tnf := LINKSRC = tnf_process_disable.3tnf - -tnfctl_buffer_dealloc.3tnf := LINKSRC = tnfctl_buffer_alloc.3tnf - -tnfctl_check_libs.3tnf := LINKSRC = tnfctl_indirect_open.3tnf - -tnfctl_continue.3tnf := LINKSRC = tnfctl_pid_open.3tnf -tnfctl_exec_open.3tnf := LINKSRC = tnfctl_pid_open.3tnf - -tnfctl_probe_apply_ids.3tnf := LINKSRC = tnfctl_probe_apply.3tnf - -tnfctl_probe_connect.3tnf := LINKSRC = tnfctl_probe_state_get.3tnf -tnfctl_probe_disable.3tnf := LINKSRC = tnfctl_probe_state_get.3tnf -tnfctl_probe_disconnect_all.3tnf := LINKSRC = tnfctl_probe_state_get.3tnf -tnfctl_probe_enable.3tnf := LINKSRC = tnfctl_probe_state_get.3tnf -tnfctl_probe_trace.3tnf := LINKSRC = tnfctl_probe_state_get.3tnf -tnfctl_probe_untrace.3tnf := LINKSRC = tnfctl_probe_state_get.3tnf -tnfctl_filter_list_add.3tnf := LINKSRC = tnfctl_trace_state_set.3tnf -tnfctl_filter_list_delete.3tnf := LINKSRC = tnfctl_trace_state_set.3tnf -tnfctl_filter_list_get.3tnf := LINKSRC = tnfctl_trace_state_set.3tnf -tnfctl_filter_state_set.3tnf := LINKSRC = tnfctl_trace_state_set.3tnf - -.KEEP_STATE: - -include $(SRC)/man/Makefile.man - -install: $(ROOTMANFILES) $(ROOTMANLINKS) diff --git a/usr/src/man/man3tnf/TNF_DECLARE_RECORD.3tnf b/usr/src/man/man3tnf/TNF_DECLARE_RECORD.3tnf deleted file mode 100644 index bb656366f2..0000000000 --- a/usr/src/man/man3tnf/TNF_DECLARE_RECORD.3tnf +++ /dev/null @@ -1,180 +0,0 @@ -'\" 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 <tnf/probe.h> - - - -\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 -<tnf/probe.h>\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 <tnf/probe.h> -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(7) 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 -.BR prex (1), -.BR tnfdump (1), -.BR TNF_PROBE (3TNF), -.BR tnf_process_disable (3TNF), -.BR attributes (7) -.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. diff --git a/usr/src/man/man3tnf/TNF_PROBE.3tnf b/usr/src/man/man3tnf/TNF_PROBE.3tnf deleted file mode 100644 index 7f5bd161bf..0000000000 --- a/usr/src/man/man3tnf/TNF_PROBE.3tnf +++ /dev/null @@ -1,332 +0,0 @@ -'\" 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(7) 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 -.BR ld (1), -.BR prex (1), -.BR tnfdump (1), -.BR dlopen (3C), -.BR TNF_DECLARE_RECORD (3TNF), -.BR libtnfctl (3TNF), -.BR tnf_process_disable (3TNF), -.BR tracing (3TNF), -.BR attributes (7), -.BR threads (7) -.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. diff --git a/usr/src/man/man3tnf/libtnfctl.3tnf b/usr/src/man/man3tnf/libtnfctl.3tnf deleted file mode 100644 index 6e0784413e..0000000000 --- a/usr/src/man/man3tnf/libtnfctl.3tnf +++ /dev/null @@ -1,472 +0,0 @@ -'\" te -.\" Copyright (c) 2004 Sun Microsystems, Inc. All Rights Reserved -.\" 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 LIBTNFCTL 3TNF "June 20, 2021" -.SH NAME -libtnfctl \- library for TNF probe control in a process or the kernel -.SH SYNOPSIS -.nf -\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-ltnfctl\fR [ \fIlibrary\fR ... ] -#include <tnf/tnfctl.h> -.fi - -.SH DESCRIPTION -The \fBlibtnfctl\fR library provides an \fBAPI\fR to control \fBTNF\fR -("Trace Normal Form") probes within a process or the kernel. See -\fBtracing\fR(3TNF) for an overview of the Solaris tracing architecture. The -client of \fBlibtnfctl\fR controls probes in one of four modes: -.sp -.ne 2 -.na -\fBinternal mode\fR -.ad -.RS 17n -The target is the controlling process itself; that is, the client controls its -own probes. -.RE - -.sp -.ne 2 -.na -\fBdirect mode\fR -.ad -.RS 17n -The target is a separate process; a client can either \fBexec\fR(2) a program -or attach to a running process for probe control. The \fBlibtnfctl\fR library -uses \fBproc\fR(5) on the target process for probe and process control in this -mode, and additionally provides basic process control features. -.RE - -.sp -.ne 2 -.na -\fBindirect mode\fR -.ad -.RS 17n -The target is a separate process, but the controlling process is already using -\fBproc\fR(5) to control the target, and hence \fBlibtnfctl\fR cannot use -those interfaces directly. Use this mode to control probes from within a -debugger. In this mode, the client must provide a set of functions that -\fBlibtnfctl\fR can use to query and update the target process. -.RE - -.sp -.ne 2 -.na -\fBkernel mode\fR -.ad -.RS 17n -The target is the Solaris kernel. -.RE - -.sp -.LP -A process is controlled "externally" if it is being controlled in either direct -mode or indirect mode. Alternatively, a process is controlled "internally" when -it uses internal mode to control its own probes. -.sp -.LP -There can be only one client at a time doing probe control on a given process. -Therefore, it is not possible for a process to be controlled internally while -it is being controlled externally. It is also not possible to have a process -controlled by multiple external processes. Similarly, there can be only one -process at a time doing kernel probe control. Note, however, that while a given -target may only be controlled by one \fBlibtnfctl\fR client, a single client -may control an arbitrary number of targets. That is, it is possible for a -process to simultaneously control its own probes, probes in other processes, -and probes in the kernel. -.sp -.LP -The following tables denotes the modes applicable to all \fBlibtnfctl\fR -interfaces (INT = internal mode; D = direct mode; IND = indirect mode; K = -kernel mode). -.sp -.LP -These interfaces create handles in the specified modes: -.sp - -.sp -.TS -l l l l l -l l l l l . -\fBtnfctl_internal_open()\fR INT -\fBtnfctl_exec_open()\fR D -\fBtnfctl_pid_open()\fR D -\fBtnfctl_indirect_open()\fR IND -\fBtnfctl_kernel_open()\fR K -.TE - -.sp -.LP -These interfaces are used with the specified modes: -.sp - -.sp -.TS -l l l l l -l l l l l . -\fBtnfctl_continue()\fR D -\fBtnfctl_probe_connect()\fR INT D IND -\fBtnfctl_probe_disconnect_all ()\fR INT D IND -\fBtnfctl_trace_attrs_get()\fR INT D IND K -\fBtnfctl_buffer_alloc()\fR INT D IND K -\fBtnfctl_register_funcs()\fR INT D IND K -\fBtnfctl_probe_apply()\fR INT D IND K -\fBtnfctl_probe_apply_ids()\fR INT D IND K -\fBtnfctl_probe_state_get ()\fR INT D IND K -\fBtnfctl_probe_enable()\fR INT D IND K -\fBtnfctl_probe_disable()\fR INT D IND K -\fBtnfctl_probe_trace()\fR INT D IND K -\fBtnfctl_probe_untrace()\fR INT D IND K -\fBtnfctl_check_libs()\fR INT D IND K -\fBtnfctl_close()\fR INT D IND K -\fBtnfctl_strerror()\fR INT D IND K -\fBtnfctl_buffer_dealloc()\fR K -\fBtnfctl_trace_state_set()\fR K -\fBtnfctl_filter_state_set()\fR K -\fBtnfctl_filter_list_get()\fR K -\fBtnfctl_filter_list_add()\fR K -\fBtnfctl_filter_list_delete()\fR K -.TE - -.sp -.LP -When using \fBlibtnfctl\fR, the first task is to create a handle for -controlling probes. The \fBtnfctl_internal_open()\fR function creates an -internal mode handle for controlling probes in the same process, as described -above. The \fBtnfctl_pid_open()\fR and \fBtnfctl_exec_open()\fR functions -create handles in direct mode. The \fBtnfctl_indirect_open()\fR function -creates an indirect mode handle, and the \fBtnfctl_kernel_open()\fR function -creates a kernel mode handle. A handle is required for use in nearly all other -\fBlibtnfctl\fR functions. The \fBtnfctl_close()\fR function releases the -resources associated with a handle. -.sp -.LP -The \fBtnfctl_continue()\fR function is used in direct mode to resume execution -of the target process. -.sp -.LP -The \fBtnfctl_buffer_alloc()\fR function allocates a trace file or, in kernel -mode, a trace buffer. -.sp -.LP -The \fBtnfctl_probe_apply()\fR and \fBtnfctl_probe_apply_ids()\fR functions -call a specified function for each probe or for a designated set of probes. -.sp -.LP -The \fBtnfctl_register_funcs()\fR function registers functions to be called -whenever new probes are seen or probes have disappeared, providing an -opportunity to do one-time processing for each probe. -.sp -.LP -The \fBtnfctl_check_libs()\fR function is used primarily in indirect mode to -check whether any new probes have appeared, that is, they have been made -available by \fBdlopen\fR(3C), or have disappeared, that is, they have -disassociated from the process by \fBdlclose\fR(3C). -.sp -.LP -The \fBtnfctl_probe_enable()\fR and \fBtnfctl_probe_disable()\fR functions -control whether the probe, when hit, will be ignored. -.sp -.LP -The \fBtnfctl_probe_trace()\fR and \fBtnfctl_probe_untrace()\fR functions -control whether an enabled probe, when hit, will cause an entry to be made in -the trace file. -.sp -.LP -The \fBtnfctl_probe_connect()\fR and \fBtnfctl_probe_disconnect_all()\fR -functions control which functions, if any, are called when an enabled probe is -hit. -.sp -.LP -The \fBtnfctl_probe_state_get()\fR function returns information about the -status of a probe, such as whether it is currently enabled. -.sp -.LP -The \fBtnfctl_trace_attrs_get()\fR function returns information about the -tracing session, such as the size of the trace buffer or trace file. -.sp -.LP -The \fBtnfctl_strerror()\fR function maps a \fBtnfctl\fR error code to a -string, for reporting purposes. -.sp -.LP -The remaining functions apply only to kernel mode. -.sp -.LP -The \fBtnfctl_trace_state_set()\fR function controls the master switch for -kernel tracing. See \fBprex\fR(1) for more details. -.sp -.LP -The \fBtnfctl_filter_state_set()\fR, \fBtnfctl_filter_list_get()\fR, -\fBtnfctl_filter_list_add()\fR, and \fBtnfctl_filter_list_delete()\fR functions -allow a set of processes to be specified for which probes will not be ignored -when hit. This prevents kernel activity caused by uninteresting processes from -cluttering up the kernel's trace buffer. -.sp -.LP -The \fBtnfctl_buffer_dealloc()\fR function deallocates the kernel's internal -trace buffer. -.SH RETURN VALUES -Upon successful completion, these functions return \fBTNFCTL_ERR_NONE\fR. -.SH ERRORS -The error codes for \fBlibtnfctl\fR are: -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_ACCES\fR\fR -.ad -.RS 28n -Permission denied. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_NOTARGET\fR\fR -.ad -.RS 28n -The target process completed. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_ALLOCFAIL\fR\fR -.ad -.RS 28n -A memory allocation failure occurred. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INTERNAL\fR\fR -.ad -.RS 28n -An internal error occurred. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_SIZETOOSMALL\fR\fR -.ad -.RS 28n -The requested trace size is too small. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_SIZETOOBIG\fR\fR -.ad -.RS 28n -The requested trace size is too big. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BADARG\fR\fR -.ad -.RS 28n -Bad input argument. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_NOTDYNAMIC\fR\fR -.ad -.RS 28n -The target is not a dynamic executable. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_NOLIBTNFPROBE\fR\fR -.ad -.RS 28n -\fBlibtnfprobe.so\fR not linked in target. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BUFBROKEN\fR\fR -.ad -.RS 28n -Tracing is broken in the target. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BUFEXISTS\fR\fR -.ad -.RS 28n -A buffer already exists. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_NOBUF\fR\fR -.ad -.RS 28n -No buffer exists. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BADDEALLOC\fR\fR -.ad -.RS 28n -Cannot deallocate buffer. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_NOPROCESS\fR\fR -.ad -.RS 28n -No such target process exists. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_FILENOTFOUND\fR\fR -.ad -.RS 28n -File not found. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BUSY\fR\fR -.ad -.RS 28n -Cannot attach to process or kernel because it is already tracing. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INVALIDPROBE\fR\fR -.ad -.RS 28n -Probe no longer valid. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_USR1\fR\fR -.ad -.RS 28n -Error code reserved for user. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_USR2\fR\fR -.ad -.RS 28n -Error code reserved for user. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_USR3\fR\fR -.ad -.RS 28n -Error code reserved for user. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_USR4\fR\fR -.ad -.RS 28n -Error code reserved for user. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_USR5\fR\fR -.ad -.RS 28n -Error code reserved for user. -.RE - -.SH ATTRIBUTES -See \fBattributes\fR(7) for descriptions of the following attributes: -.sp - -.sp -.TS -box; -c | c -l | l . -ATTRIBUTE TYPE ATTRIBUTE VALUE -_ -MT Level MT-Safe with exceptions -.TE - -.SH SEE ALSO -.BR prex (1), -.BR exec (2), -.BR dlclose (3C), -.BR dlopen (3C), -.BR libtnfctl (3LIB), -.BR TNF_PROBE (3TNF), -.BR tnfctl_buffer_alloc (3TNF), -.BR tnfctl_buffer_dealloc (3TNF), -.BR tnfctl_check_libs (3TNF), -.BR tnfctl_close (3TNF), -.BR tnfctl_continue (3TNF), -.BR tnfctl_exec_open (3TNF), -.BR tnfctl_filter_list_add (3TNF), -.BR tnfctl_filter_list_delete (3TNF), -.BR tnfctl_filter_list_get (3TNF), -.BR tnfctl_filter_state_set (3TNF), -.BR tnfctl_indirect_open (3TNF), -.BR tnfctl_internal_open (3TNF), -.BR tnfctl_kernel_open (3TNF), -.BR tnfctl_pid_open (3TNF), -.BR tnfctl_probe_apply (3TNF), -.BR tnfctl_probe_apply_ids (3TNF), -.BR tnfctl_probe_connect (3TNF), -.BR tnfctl_probe_disable (3TNF), -.BR tnfctl_probe_enable (3TNF), -.BR tnfctl_probe_state_get (3TNF), -.BR tnfctl_probe_trace (3TNF), -.BR tnfctl_probe_untrace (3TNF), -.BR tnfctl_register_funcs (3TNF), -.BR tnfctl_strerror (3TNF), -.BR tnfctl_trace_attrs_get (3TNF), -.BR tnfctl_trace_state_set (3TNF), -.BR proc (5), -.BR attributes (7) -.sp -.LP -\fILinker and Libraries Guide\fR -.SH NOTES -This \fBAPI\fR is MT-Safe. Multiple threads may concurrently operate on -independent \fBtnfctl\fR handles, which is the typical behavior expected. The -\fBlibtnfctl\fR library does not support multiple threads operating on the same -\fBtnfctl\fR handle. If this is desired, it is the client's responsibility to -implement locking to ensure that two threads that use the same \fBtnfctl\fR -handle are not simultaneously in a \fBlibtnfctl\fR interface. diff --git a/usr/src/man/man3tnf/tnf_process_disable.3tnf b/usr/src/man/man3tnf/tnf_process_disable.3tnf deleted file mode 100644 index 2042da9c7f..0000000000 --- a/usr/src/man/man3tnf/tnf_process_disable.3tnf +++ /dev/null @@ -1,119 +0,0 @@ -'\" te -.\" Copyright 2002 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_PROCESS_DISABLE 3TNF "Feb 5, 2002" -.SH NAME -tnf_process_disable, tnf_process_enable, tnf_thread_disable, tnf_thread_enable -\- probe control internal interface -.SH SYNOPSIS -.LP -.nf -\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-ltnfprobe\fR [ \fIlibrary\fR ... ] -#include <tnf/probe.h> - - - -\fBvoid\fR \fBtnf_process_disable\fR(\fBvoid\fR); -.fi - -.LP -.nf -\fBvoid\fR \fBtnf_process_enable\fR(\fBvoid\fR); -.fi - -.LP -.nf -\fBvoid\fR \fBtnf_thread_disable\fR(\fBvoid\fR); -.fi - -.LP -.nf -\fBvoid\fR \fBtnf_thread_enable\fR(\fBvoid\fR); -.fi - -.SH DESCRIPTION -.sp -.LP -There are three levels of granularity for controlling tracing and probe -functions (called probing from here on): probing for the entire process, a -particular thread, and the probe itself can be disabled or enabled. The first -two (process and thread) are controlled by this interface. The probe is -controlled with the \fBprex\fR(1) utility. -.sp -.LP -The \fBtnf_process_disable()\fR function turns off probing for the process. The -default process state is to have probing enabled. The -\fBtnf_process_enable()\fR function turns on probing for the process. -.sp -.LP -The \fBtnf_thread_disable()\fR function turns off probing for the currently -running thread. Threads are "born" or created with this state enabled. The -\fBtnf_thread_enable()\fR function turns on probing for the currently running -thread. If the program is a non-threaded program, these two thread interfaces -disable or enable probing for the process. -.SH ATTRIBUTES -.sp -.LP -See \fBattributes\fR(7) for descriptions of the following attributes: -.sp - -.sp -.TS -box; -c | c -l | l . -ATTRIBUTE TYPE ATTRIBUTE VALUE -_ -Interface Stability Unstable -_ -MT-Level MT-Safe -.TE - -.SH SEE ALSO -.sp -.LP -.BR prex (1), -.BR tnfdump (1), -.BR TNF_DECLARE_RECORD (3TNF), -.BR TNF_PROBE (3TNF), -.BR attributes (7) -.SH NOTES -.sp -.LP -A probe is considered enabled only if: -.RS +4 -.TP -.ie t \(bu -.el o -\fBprex\fR(1) has enabled the probe AND -.RE -.RS +4 -.TP -.ie t \(bu -.el o -the process has probing enabled, which is the default or could be set with -\fBtnf_process_enable()\fR AND -.RE -.RS +4 -.TP -.ie t \(bu -.el o -the thread that hits the probe has probing enabled, which is every thread's -default or could be set with \fBtnf_thread_enable()\fR. -.RE -.sp -.LP -There is a run time cost associated with determining that the probe is -disabled. To reduce the performance effect of probes, this cost should be -minimized. The quickest way that a probe can be determined to be disabled is -by the enable control that \fBprex\fR(1) uses. Therefore, to disable all the -probes in a process use the \fBdisable\fR command in \fBprex\fR(1) rather than -\fBtnf_process_disable()\fR. -.sp -.LP -The \fBtnf_process_disable()\fR and \fBtnf_process_enable()\fR functions should -only be used to toggle probing based on some internal program condition. The -\fBtnf_thread_disable()\fR function should be used to turn off probing for -threads that are uninteresting. diff --git a/usr/src/man/man3tnf/tnfctl_buffer_alloc.3tnf b/usr/src/man/man3tnf/tnfctl_buffer_alloc.3tnf deleted file mode 100644 index 1d7a7f5666..0000000000 --- a/usr/src/man/man3tnf/tnfctl_buffer_alloc.3tnf +++ /dev/null @@ -1,207 +0,0 @@ -'\" te -.\" Copyright (c) 1996 Sun Microsystems, Inc. All Rights Reserved -.\" 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 TNFCTL_BUFFER_ALLOC 3TNF "Mar 4, 1997" -.SH NAME -tnfctl_buffer_alloc, tnfctl_buffer_dealloc \- allocate or deallocate a buffer -for trace data -.SH SYNOPSIS -.LP -.nf -\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-ltnfctl\fR [ \fIlibrary\fR ... ] -#include <tnf/tnfctl.h> -\fBtnfctl_errcode_t\fR \fBtnfctl_buffer_alloc\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR, - \fBconst char *\fR\fItrace_file_name\fR, \fBsize_t\fR \fItrace_buffer_size\fR); -.fi - -.LP -.nf -\fB\fR\fBtnfctl_buffer_dealloc\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR); -.fi - -.SH DESCRIPTION -.sp -.LP -\fBtnfctl_buffer_alloc()\fR allocates a buffer to which trace events are -logged. When tracing a process using a \fBtnfctl\fR handle returned by -\fBtnfctl_pid_open\fR(3TNF), \fBtnfctl_exec_open\fR(3TNF), -\fBtnfctl_indirect_open\fR(3TNF), and \fBtnfctl_internal_open\fR(3TNF)), -\fItrace_file_name\fR is the name of the trace file to which trace events -should be logged. It can be an absolute path specification or a relative path -specification. If it is relative, the current working directory of the process -that is calling \fBtnfctl_buffer_alloc()\fR is prefixed to -\fItrace_file_name\fR. If the named trace file already exists, it is -overwritten. For kernel tracing, that is, for a tnfctl handle returned by -\fBtnfctl_kernel_open\fR(3TNF), trace events are logged to a trace buffer in -memory; therefore, \fItrace_file_name\fR is ignored. Use \fBtnfxtract\fR(1) to -extract a kernel buffer into a file. -.sp -.LP -\fItrace_buffer_size\fR is the size in bytes of the trace buffer that should be -allocated. An error is returned if an attempt is made to allocate a buffer when -one already exists. \fBtnfctl_buffer_alloc()\fR affects the trace attributes; -use \fBtnfctl_trace_attrs_get\fR(3TNF) to get the latest trace attributes -after a buffer is allocated. -.sp -.LP -\fBtnfctl_buffer_dealloc()\fR is used to deallocate a kernel trace buffer that -is no longer needed. \fIhndl\fR must be a kernel handle, returned by -\fBtnfctl_kernel_open\fR(3TNF). A process's trace file cannot be deallocated -using \fBtnfctl_buffer_dealloc()\fR. Instead, once the trace file is no longer -needed for analysis and after the process being traced exits, use \fBrm\fR(1) -to remove the trace file. Do not remove the trace file while the process being -traced is still alive. \fBtnfctl_buffer_dealloc()\fR affects the trace -attributes; use \fBtnfctl_trace_attrs_get\fR(3TNF) to get the latest trace -attributes after a buffer is deallocated. -.sp -.LP -For a complete discussion of \fBtnf tracing\fR, see \fBtracing\fR(3TNF). -.SH RETURN VALUES -.sp -.LP -\fBtnfctl_buffer_alloc()\fR and \fBtnfctl_buffer_dealloc()\fR return -\fBTNFCTL_ERR_NONE\fR upon success. -.SH ERRORS -.sp -.LP -The following error codes apply to \fBtnfctl_buffer_alloc()\fR: -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BUFEXISTS\fR\fR -.ad -.RS 27n -A buffer already exists. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_ACCES\fR\fR -.ad -.RS 27n -Permission denied; could not create a trace file. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_SIZETOOSMALL\fR\fR -.ad -.RS 27n -The \fItrace_buffer_size\fR requested is smaller than the minimum trace buffer -size needed. Use \fBtrace_min_size\fR of trace attributes in -\fBtnfctl_trace_attrs_get\fR(3TNF) to determine the minimum size of the buffer. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_SIZETOOBIG\fR\fR -.ad -.RS 27n -The requested trace file size is too big. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BADARG\fR\fR -.ad -.RS 27n -\fItrace_file_name\fR is \fINULL\fR or the absolute path name is longer than -\fBMAX\fR\fBPATH\fR\fBLEN.\fR -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_ALLOCFAIL\fR\fR -.ad -.RS 27n -A memory allocation failure occurred. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INTERNAL\fR\fR -.ad -.RS 27n -An internal error occurred. -.RE - -.sp -.LP -The following error codes apply to \fBtnfctl_buffer_dealloc()\fR: -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BADARG\fR\fR -.ad -.RS 25n -\fIhndl\fR is not a kernel handle. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_NOBUF\fR\fR -.ad -.RS 25n -No buffer exists to deallocate. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BADDEALLOC\fR\fR -.ad -.RS 25n -Cannot deallocate a trace buffer unless tracing is stopped. Use -\fBtnfctl_trace_state_set\fR(3TNF) to stop tracing. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INTERNAL\fR\fR -.ad -.RS 25n -An internal error occurred. -.RE - -.SH ATTRIBUTES -.sp -.LP -See \fBattributes\fR(7) 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 -.BR prex (1), -.BR rm (1), -.BR tnfxtract (1), -.BR TNF_PROBE (3TNF), -.BR libtnfctl (3TNF), -.BR tnfctl_exec_open (3TNF), -.BR tnfctl_indirect_open (3TNF), -.BR tnfctl_internal_open (3TNF), -.BR tnfctl_kernel_open (3TNF), -.BR tnfctl_pid_open (3TNF), -.BR tnfctl_trace_attrs_get (3TNF), -.BR tracing (3TNF), -.BR attributes (7) diff --git a/usr/src/man/man3tnf/tnfctl_close.3tnf b/usr/src/man/man3tnf/tnfctl_close.3tnf deleted file mode 100644 index 1d1a732e05..0000000000 --- a/usr/src/man/man3tnf/tnfctl_close.3tnf +++ /dev/null @@ -1,129 +0,0 @@ -'\" te -.\" Copyright (c) 1996 Sun Microsystems, Inc. All Rights Reserved -.\" 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 TNFCTL_CLOSE 3TNF "Mar 4, 1997" -.SH NAME -tnfctl_close \- close a tnfctl handle -.SH SYNOPSIS -.LP -.nf -\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-ltnfctl\fR [ \fIlibrary\fR ... ] -#include <tnf/tnfctl.h> -\fBtnfctl_errcode_t\fR \fBtnfctl_close\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR, - \fBtnfctl_targ_op_t\fR \fIaction\fR); -.fi - -.SH DESCRIPTION -.sp -.LP -\fBtnfctl_close()\fR is used to close a tnfctl handle and to free up the memory -associated with the handle. When the handle is closed, the tracing state and -the states of the probes are not changed. \fBtnfctl_close()\fR can be used to -close handles in any mode, that is, whether they were created by -\fBtnfctl_internal_open\fR(3TNF), \fBtnfctl_pid_open\fR(3TNF), -\fBtnfctl_exec_open\fR(3TNF), \fBtnfctl_indirect_open\fR(3TNF), or -\fBtnfctl_kernel_open\fR(3TNF). -.sp -.LP -The \fIaction\fR argument is only used in direct mode, that is, if \fIhndl\fR -was created by \fBtnfctl_exec_open\fR(3TNF) or \fBtnfctl_pid_open\fR(3TNF). In -direct mode, \fIaction\fR specifies whether the process will proceed, be -killed, or remain suspended. \fIaction\fR may have the following values: -.sp -.ne 2 -.na -\fB\fBTNFCTL_TARG_DEFAULT\fR\fR -.ad -.RS 23n -Kills the target process if \fIhndl\fR was created with -\fBtnfctl_exec_open\fR(3TNF), but lets it continue if it was created with -\fBtnfctl_pid_open\fR(3TNF). -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_TARG_KILL\fR\fR -.ad -.RS 23n -Kills the target process. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_TARG_RESUME\fR\fR -.ad -.RS 23n -Allows the target process to continue. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_TARG_SUSPEND\fR\fR -.ad -.RS 23n -Leaves the target process suspended. This is not a job control suspend. It is -possible to attach to the process again with a debugger or with the -\fBtnfctl_pid_open\fR(3TNF) interface. The target process can also be -continued with \fBprun\fR(1). -.RE - -.SH RETURN VALUES -.sp -.LP -\fBtnfctl_close()\fR returns \fBTNFCTL_ERR_NONE\fR upon success. -.SH ERRORS -.sp -.LP -The following error codes apply to \fBtnfctl_close()\fR: -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BADARG\fR\fR -.ad -.RS 23n -A bad argument was sent in \fIaction\fR. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INTERNAL\fR\fR -.ad -.RS 23n -An internal error occurred. -.RE - -.SH ATTRIBUTES -.sp -.LP -See \fBattributes\fR(7) 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 -.BR prex (1), -.BR prun (1), -.BR TNF_PROBE (3TNF), -.BR libtnfctl (3TNF), -.BR tnfctl_exec_open (3TNF), -.BR tnfctl_indirect_open (3TNF), -.BR tnfctl_kernel_open (3TNF), -.BR tnfctl_pid_open (3TNF), -.BR tracing (3TNF), -.BR attributes (7) diff --git a/usr/src/man/man3tnf/tnfctl_indirect_open.3tnf b/usr/src/man/man3tnf/tnfctl_indirect_open.3tnf deleted file mode 100644 index 4708ff4948..0000000000 --- a/usr/src/man/man3tnf/tnfctl_indirect_open.3tnf +++ /dev/null @@ -1,210 +0,0 @@ -'\" te -.\" Copyright (c) 2004 Sun Microsystems, Inc. All Rights Reserved -.\" 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 TNFCTL_INDIRECT_OPEN 3TNF "August 29, 2021" -.SH NAME -tnfctl_indirect_open, tnfctl_check_libs \- control probes of another process -where caller provides /proc functionality -.SH SYNOPSIS -.nf -\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-ltnfctl\fR [ \fIlibrary\fR ... ] -#include <tnf/tnfctl.h> - -\fBtnfctl_errcode_t\fR \fBtnfctl_indirect_open\fR(\fBvoid *\fR\fIprochandle\fR, - \fBtnfctl_ind_config_t *\fR\fIconfig\fR, \fBtnfctl_handle_t **\fR\fIret_val\fR); -.fi - -.LP -.nf -\fBtnfctl_errcode_t\fR \fBtnfctl_check_libs\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR); -.fi - -.SH DESCRIPTION -The interfaces \fBtnfctl_indirect_open()\fR and \fBtnfctl_check_libs()\fR are -used to control probes in another process where the \fBlibtnfctl\fR(3TNF) -client has already opened \fBproc\fR(5) on the target process. An example of -this is when the client is a debugger. Since these clients already use -\fB/proc\fR on the target, \fBlibtnfctl\fR(3TNF) cannot use \fB/proc\fR -directly. Therefore, these clients must provide callback functions that can be -used to inspect and to update the target process. The target process must -load \fBlibtnfprobe.so.1\fR (defined in \fB<tnf/tnfctl.h>\fR as macro -\fBTNFCTL_LIBTNFPROBE).\fR -.sp -.LP -The first argument \fIprochandle\fR is a pointer to an opaque structure that is -used in the callback functions that inspect and update the target process. -This structure should encapsulate the state that the caller needs to use -\fB/proc\fR on the target process (the \fB/proc\fR file descriptor). The -second argument, \fIconfig\fR, is a pointer to -.sp -.in +2 -.nf -typedef -struct tnfctl_ind_config { - int (*p_read)(void *prochandle, paddr_t addr, char *buf, - size_t size); - int (*p_write)(void *prochandle, paddr_t addr, char *buf, - size_t size); - pid_t (*p_getpid)(void *prochandle); - int (*p_obj_iter)(void *prochandle, tnfctl_ind_obj_f *func, - void *client_data); -} tnfctl_ind_config_t; -.fi -.in -2 - -.sp -.LP -The first field \fIp_read\fR is the address of a function that can read -\fBsize\fR bytes at address \fIaddr\fR in the target image into the buffer -\fIbuf\fR. The function should return \fB0\fR upon success. The second field -\fIp_write\fR is the address of a function that can write \fBsize\fR bytes at -address \fIaddr\fR in the target image from the buffer \fIbuf\fR. The function -should return \fB0\fR upon success. The third field \fIp_getpid\fR is the -address of a function that should return the process id of the target process -(\fIprochandle\fR). The fourth field \fIp_obj_iter\fR is the address of a -function that iterates over all load objects and the executable by calling the -callback function \fIfunc\fR with \fIclient_data\fR. If \fIfunc\fR returns -\fB0\fR, \fIp_obj_iter\fR should continue processing link objects. If -\fIfunc\fR returns any other value, \fIp_obj_iter\fR should stop calling the -callback function and return that value. \fIp_obj_iter\fR should return -\fB0\fR if it iterates over all load objects. -.sp -.LP -If a failure is returned by any of the functions in \fIconfig\fR, the error is -propagated back as \fBPREX_ERR_INTERNAL\fR by the \fBlibtnfctl\fR interface -that called it. -.sp -.LP -The definition of \fBtnfctl_ind_obj_f\fR is: -.sp -.in +2 -.nf -typedef int -tnfctl_ind_obj_f(void *prochandle, - const struct tnfctl_ind_obj_info *obj - void *client_data); -typedef struct tnfctl_ind_obj_info { - int objfd; /* -1 indicates fd not available */ - paddr_t text_base; /* virtual addr of text segment */ - paddr_t data_base; /* virtual addr of data segment */ - const char *objname; /* null-term. pathname to loadobj */ -} tnfctl_ind_obj_info_t; -.fi -.in -2 - -.sp -.LP -\fIobjfd\fR should be the file descriptor of the load object or executable. If -it is \fB\(mi1\fR, then \fIobjname\fR should be an absolute pathname to the -load object or executable. If \fIobjfd\fR is not closed by \fBlibtnfctl\fR, it -should be closed by the load object iterator function. \fItext_base\fR and -\fIdata_base\fR are the addresses where the text and data segments of the load -object are mapped in the target process. -.sp -.LP -Whenever the target process opens or closes a dynamic object, the set of -available probes may change. See \fBdlopen\fR(3C) and \fBdlclose\fR(3C). In -indirect mode, call \fBtnfctl_check_libs()\fR when such events occur to make -\fBlibtnfctl\fR aware of any changes. In other modes this is unnecessary but -harmless. It is also harmless to call \fBtnfctl_check_libs()\fR when no such -events have occurred. -.SH RETURN VALUES -\fBtnfctl_indirect_open()\fR and \fBtnfctl_check_libs()\fR return -\fBTNFCTL_ERR_NONE\fR upon success. -.SH ERRORS -The following error codes apply to \fBtnfctl_indirect_open()\fR: -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_ALLOCFAIL\fR\fR -.ad -.RS 28n -A memory allocation failure occurred. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BUSY\fR\fR -.ad -.RS 28n -Internal tracing is being used. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_NOLIBTNFPROBE\fR\fR -.ad -.RS 28n -\fBlibtnfprobe.so.1\fR is not loaded in the target process. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INTERNAL\fR\fR -.ad -.RS 28n -An internal error occurred. -.RE - -.sp -.LP -The following error codes apply to \fBtnfctl_check_libs()\fR: -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_ALLOCFAIL\fR\fR -.ad -.RS 24n -A memory allocation failure occurred. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INTERNAL\fR\fR -.ad -.RS 24n -An internal error occurred. -.RE - -.SH ATTRIBUTES -See \fBattributes\fR(7) 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 -.BR prex (1), -.BR dlclose (3C), -.BR dlopen (3C), -.BR TNF_PROBE (3TNF), -.BR libtnfctl (3TNF), -.BR tnfctl_probe_enable (3TNF), -.BR tnfctl_probe_trace (3TNF), -.BR tracing (3TNF), -.BR proc (5), -.BR attributes (7) -.sp -.LP -\fILinker and Libraries Guide\fR -.SH NOTES -\fBtnfctl_indirect_open()\fR should only be called after the dynamic linker has -mapped in all the libraries (rtld sync point) and called only after the process -is stopped. Indirect process probe control assumes the target process is -stopped whenever any \fBlibtnfctl\fR interface is used on it. For example, -when used for indirect process probe control, \fBtnfctl_probe_enable\fR(3TNF) -and \fBtnfctl_probe_trace\fR(3TNF) should be called only for a process that is -stopped. diff --git a/usr/src/man/man3tnf/tnfctl_internal_open.3tnf b/usr/src/man/man3tnf/tnfctl_internal_open.3tnf deleted file mode 100644 index c3062712c1..0000000000 --- a/usr/src/man/man3tnf/tnfctl_internal_open.3tnf +++ /dev/null @@ -1,126 +0,0 @@ -'\" te -.\" Copyright (c) 2004 Sun Microsystems, Inc. All Rights Reserved -.\" 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 TNFCTL_INTERNAL_OPEN 3TNF "Mar 1, 2004" -.SH NAME -tnfctl_internal_open \- create handle for internal process probe control -.SH SYNOPSIS -.LP -.nf -\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-ltnfctl\fR [ \fIlibrary\fR ... ] -#include <tnf/tnfctl.h> - - - -\fBtnfctl_errcode_t\fR \fBtnfctl_internal_open\fR(\fBtnfctl_handle_t **\fR\fIret_val\fR); -.fi - -.SH DESCRIPTION -.sp -.LP -\fBtnfctl_internal_open()\fR returns in \fIret_val\fR a pointer to an opaque -handle that can be used to control probes in the same process as the caller -(internal process probe control). The process must have \fBlibtnfprobe.so.1\fR -loaded. Probes in libraries that are brought in by \fBdlopen\fR(3C) will be -visible after the library has been opened. Probes in libraries closed by a -\fBdlclose\fR(3C) will not be visible after the library has been disassociated. -See the \fBNOTES\fR section for more details. -.SH RETURN VALUES -.sp -.LP -\fBtnfctl_internal_open()\fR returns \fBTNFCTL_ERR_NONE\fR upon success. -.SH ERRORS -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_ALLOCFAIL\fR\fR -.ad -.RS 28n -A memory allocation failure occurred. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BUSY\fR\fR -.ad -.RS 28n -Another client is already tracing this program (internally or externally). -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_NOLIBTNFPROBE\fR\fR -.ad -.RS 28n -\fBlibtnfprobe.so.1\fR is not linked in the target process. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INTERNAL\fR\fR -.ad -.RS 28n -An internal error occurred. -.RE - -.SH ATTRIBUTES -.sp -.LP -See \fBattributes\fR(7) 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 -.BR ld (1), -.BR prex (1), -.BR dlclose (3C), -.BR dlopen (3C), -.BR TNF_PROBE (3TNF), -.BR libtnfctl (3TNF), -.BR tracing (3TNF), -.BR attributes (7) -.sp -.LP -\fILinker and Libraries Guide\fR -.SH NOTES -.sp -.LP -\fBlibtnfctl\fR interposes on \fBdlopen\fR(3C) and \fBdlclose\fR(3C) in order -to be notified of libraries being dynamically opened and closed. This -interposition is necessary for internal process probe control to update its -list of probes. In these interposition functions, a lock is acquired to -synchronize on traversal of the library list maintained by the runtime linker. -To avoid deadlocking on this lock, \fBtnfctl_internal_open()\fR should not be -called from within the init section of a library that can be opened by -\fBdlopen\fR(3C). -.sp -.LP -Since interposition does not work as expected when a library is opened -dynamically, \fBtnfctl_internal_open()\fR should not be used if the client -opened \fBlibtnfctl\fR through \fBdlopen\fR(3C). In this case, the client -program should be built with a static dependency on \fBlibtnfctl.\fR Also, if -the client program is explicitly linking in \fB-ldl\fR, it should link -\fB-ltnfctl\fR before \fB-ldl\fR. -.sp -.LP -Probes in filtered libraries (see \fBld\fR(1)) will not be seen because the -filtee (backing library) is loaded lazily on the first symbol reference and not -at process startup or \fBdlopen\fR(3C) time. A workaround is to call -\fBtnfctl_check_libs\fR(3TNF) once the caller is sure that the filtee has been -loaded. diff --git a/usr/src/man/man3tnf/tnfctl_kernel_open.3tnf b/usr/src/man/man3tnf/tnfctl_kernel_open.3tnf deleted file mode 100644 index e9d23afd5a..0000000000 --- a/usr/src/man/man3tnf/tnfctl_kernel_open.3tnf +++ /dev/null @@ -1,117 +0,0 @@ -'\" te -.\" Copyright (c) 1996 Sun Microsystems, Inc. All Rights Reserved -.\" 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 TNFCTL_KERNEL_OPEN 3TNF "Mar 4, 1997" -.SH NAME -tnfctl_kernel_open \- create handle for kernel probe control -.SH SYNOPSIS -.LP -.nf -\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-ltnfctl\fR [ \fIlibrary\fR ... ] -#include <tnf/tnfctl.h> - - - -\fBtnfctl_errcode_t\fR \fBtnfctl_kernel_open\fR(\fBtnfctl_handle_t **\fR\fIret_val\fR); -.fi - -.SH DESCRIPTION -.sp -.LP -\fBtnfctl_kernel_open()\fR starts a kernel tracing session and returns in -\fBret_val\fR an opaque handle that can be used to control tracing and probes -in the kernel. Only one kernel tracing session is possible at a time on a -given machine. An error code of \fBTNFCTL_ERR_BUSY\fR is returned if there is -another process using kernel tracing. Use the command -.sp -.in +2 -.nf -\fBfuser\fR \fB-f\fR \fB/dev/tnfctl\fR -.fi -.in -2 -.sp - -.sp -.LP -to print the process id of the process currently using kernel tracing. Only a -superuser may use \fBtnfctl_kernel_open()\fR. An error code of -\fBTNFCTL_ERR_ACCES\fR is returned if the caller does not have the necessary -privileges. -.SH RETURN VALUES -.sp -.LP -\fBtnfctl_kernel_open\fR returns \fBTNFCTL_ERR_NONE\fR upon success. -.SH ERRORS -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_ACCES\fR\fR -.ad -.RS 27n -Permission denied. Superuser privileges are needed for kernel tracing. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BUSY\fR\fR -.ad -.RS 27n -Another client is currently using kernel tracing. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_ALLOCFAIL\fR\fR -.ad -.RS 27n -Memory allocation failed. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_FILENOTFOUND\fR\fR -.ad -.RS 27n -\fB/dev/tnfctl\fR not found. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INTERNAL\fR\fR -.ad -.RS 27n -Some other failure occurred. -.RE - -.SH ATTRIBUTES -.sp -.LP -See \fBattributes\fR(7) 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 -.BR prex (1), -.BR TNF_PROBE (3TNF), -.BR libtnfctl (3TNF), -.BR tracing (3TNF), -.BR tnf_kernel_probes (5), -.BR attributes (7), -.BR fuser (8) diff --git a/usr/src/man/man3tnf/tnfctl_pid_open.3tnf b/usr/src/man/man3tnf/tnfctl_pid_open.3tnf deleted file mode 100644 index ad6257600a..0000000000 --- a/usr/src/man/man3tnf/tnfctl_pid_open.3tnf +++ /dev/null @@ -1,499 +0,0 @@ -'\" te -.\" Copyright (c) 2004 Sun Microsystems, Inc. All Rights Reserved -.\" 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 TNFCTL_PID_OPEN 3TNF "Mar 1, 2004" -.SH NAME -tnfctl_pid_open, tnfctl_exec_open, tnfctl_continue \- interfaces for direct -probe and process control for another process -.SH SYNOPSIS -.LP -.nf -\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-ltnfctl\fR [ \fIlibrary\fR ... ] -#include <tnf/tnfctl.h> - -\fBtnfctl_errcode_t\fR \fBtnfctl_pid_open\fR(\fBpid_t\fR \fIpid\fR, \fBtnfctl_handle_t **\fR\fIret_val\fR); -.fi - -.LP -.nf -\fBtnfctl_errcode_t\fR \fBtnfctl_exec_open\fR(\fBconst char *\fR\fIpgm_name\fR, - \fBchar * const *\fR\fIargv\fR, \fBchar * const *\fR\fIenvp\fR, - \fBconst char *\fR\fIlibnfprobe_path\fR, \fBconst char *\fR\fIld_preload\fR, - \fBtnfctl_handle_t **\fR\fIret_val\fR); -.fi - -.LP -.nf -\fBtnfctl_errcode_t\fR \fBtnfctl_continue\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR, - \fBtnfctl_event_t *\fR\fIevt\fR, \fBtnfctl_handle_t **\fR\fIchild_hndl\fR); -.fi - -.SH DESCRIPTION -.sp -.LP -The \fBtnfctl_pid_open()\fR, \fBtnfctl_exec_open()\fR, and -\fBtnfctl_continue()\fR functions create handles to control probes in another -process (direct process probe control). Either \fBtnfctl_pid_open()\fR or -\fBtnfctl_exec_open()\fR will return a handle in \fIret_val\fR that can be used -for probe control. On return of these calls, the process is stopped. -\fBtnfctl_continue()\fR allows the process specified by \fIhndl\fR to continue -execution. -.sp -.LP -The \fBtnfctl_pid_open()\fR function attaches to a running process with process -id of \fIpid\fR. The process is stopped on return of this call. The -\fBtnfctl_pid_open()\fR function returns an error message if \fIpid\fR is the -same as the calling process. See \fBtnfctl_internal_open\fR(3TNF) for -information on internal process probe control. A pointer to an opaque handle is -returned in \fIret_val\fR, which can be used to control the process and the -probes in the process. The target process must have \fBlibtnfprobe.so.1\fR -(defined in <\fBtnf/tnfctl.h\fR> as macro \fBTNFCTL_LIBTNFPROBE)\fR linked in -for probe control to work. -.sp -.LP -The \fBtnfctl_exec_open()\fR function is used to \fBexec\fR(2) a program and -obtain a probe control handle. For probe control to work, the process image to -be \fBexec\fR'd must load \fBlibtnfprobe.so.1\fR. The \fBtnfctl_exec_open()\fR -function makes it simple for the library to be loaded at process start up time. -The \fIpgm_name\fR argument is the command to \fBexec\fR. If \fIpgm_name\fR is -not an absolute path, then the \fB$PATH\fR environment variable is used to -find the \fIpgm_name\fR. \fIargv\fR is a null-terminated argument pointer, that -is, it is a null-terminated array of pointers to null-terminated strings. These -strings constitute the argument list available to the new process image. The -\fIargv\fR argument must have at least one member, and it should point to a -string that is the same as \fIpgm_name\fR. See \fBexecve\fR(2). The -\fIlibnfprobe_path\fR argument is an optional argument, and if set, it should -be the path to the directory that contains \fBlibtnfprobe.so.1\fR. There is no -need for a trailing "/" in this argument. This argument is useful if -\fBlibtnfprobe.so.1\fR is not installed in \fB/usr/lib\fR. \fIld_preload\fR is -a space-separated list of libraries to preload into the target program. This -string should follow the syntax guidelines of the \fBLD_PRELOAD\fR environment -variable. See \fBld.so.1\fR(1). The following illustrates how strings are -concatenated to form the \fBLD_PRELOAD\fR environment variable in the new -process image: -.sp -.in +2 -.nf -<current value of $LD_PRELOAD> + <space> + -libtnfprobe_path + "/libtnfprobe.so.1" +<space> + -ld_preload -.fi -.in -2 - -.sp -.LP -This option is useful for preloading interposition libraries that have probes -in them. -.sp -.LP -\fIenvp\fR is an optional argument, and if set, it is used for the environment -of the target program. It is a null-terminated array of pointers to -null-terminated strings. These strings constitute the environment of the new -process image. See \fBexecve\fR(2). If \fIenvp\fR is set, it overrides -\fIld_preload\fR. In this case, it is the caller's responsibility to ensure -that \fBlibtnfprobe.so.1\fR is loaded into the target program. If \fIenvp\fR -is not set, the new process image inherits the environment of the calling -process, except for \fBLD_PRELOAD\fR. -.sp -.LP -The \fIret_val\fR argument is the handle that can be used to control the -process and the probes within the process. Upon return, the process is stopped -before any user code, including \fB\&.init\fR sections, has been executed. -.sp -.LP -The \fBtnfctl_continue()\fR function is a blocking call and lets the target -process referenced by \fIhndl\fR continue running. It can only be used on -handles returned by \fBtnfctl_pid_open()\fR and \fBtnfctl_exec_open()\fR -(direct process probe control). It returns when the target stops; the reason -that the process stopped is returned in \fIevt\fR. This call is interruptible -by signals. If it is interrupted, the process is stopped, and -\fBTNFCTL_EVENT_EINTR\fR is returned in \fIevt\fR. The client of this library -will have to decide which signal implies a stop to the target and catch that -signal. Since a signal interrupts \fBtnfctl_continue()\fR, it will return, and -the caller can decide whether or not to call \fBtnfctl_continue()\fR again. -.sp -.LP -\fBtnfctl_continue()\fR returns with an event of \fBTNFCTL_EVENT_DLOPEN\fR, -\fBTNFCTL_EVENT_DLCLOSE\fR, \fBTNFCTL_EVENT_EXEC\fR, \fBTNFCTL_EVENT_FORK\fR, -\fBTNFCTL_EVENT_EXIT\fR, or \fBTNFCTL_EVENT_TARGGONE\fR, respectively, when the -target program calls \fBdlopen\fR(3C), \fBdlclose\fR(3C), any flavor of -\fBexec\fR(2), \fBfork\fR(2) (or \fBfork1\fR(2)), \fBexit\fR(2), or terminates -unexpectedly. If the target program called \fBexec\fR(2), the client then needs -to call \fBtnfctl_close\fR(3TNF) on the current handle leaving the target -resumed, suspended, or killed (second argument to \fBtnfctl_close\fR(3TNF)). -No other \fBlibtnfctl\fR interface call can be used on the existing handle. If -the client wants to control the \fBexec\fR'ed image, it should leave the old -handle suspended, and use \fBtnfctl_pid_open()\fR to reattach to the same -process. This new handle can then be used to control the \fBexec\fR'ed image. -See \fBEXAMPLES\fR below for sample code. If the target process did a -\fBfork\fR(2) or \fBfork1\fR(2), and if control of the child process is not -needed, then \fIchild_hndl\fR should be \fINULL\fR. If control of the child -process is needed, then \fIchild_hndl\fR should be set. If it is set, a -pointer to a handle that can be used to control the child process is returned -in \fIchild_hndl\fR. The child process is stopped at the end of the -\fBfork()\fR system call. See \fBEXAMPLES\fR for an example of this event. -.SH RETURN VALUES -.sp -.LP -The \fBtnfctl_pid_open()\fR, \fBtnfctl_exec_open()\fR, and -\fBtnfctl_continue()\fR functions return \fBTNFCTL_ERR_NONE\fR upon success. -.SH ERRORS -.sp -.LP -The following error codes apply to \fBtnfctl_pid_open()\fR: -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BADARG\fR\fR -.ad -.RS 28n -The \fIpid\fR specified is the same process. Use -\fBtnfctl_internal_open\fR(3TNF) instead. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_ACCES\fR\fR -.ad -.RS 28n -Permission denied. No privilege to connect to a setuid process. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_ALLOCFAIL\fR\fR -.ad -.RS 28n -A memory allocation failure occurred. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BUSY\fR\fR -.ad -.RS 28n -Another client is already using \fB/proc\fR to control this process or -internal tracing is being used. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_NOTDYNAMIC\fR\fR -.ad -.RS 28n -The process is not a dynamic executable. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_NOPROCESS\fR\fR -.ad -.RS 28n -No such target process exists. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_NOLIBTNFPROBE\fR\fR -.ad -.RS 28n -\fBlibtnfprobe.so.1\fR is not linked in the target process. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INTERNAL\fR\fR -.ad -.RS 28n -An internal error occurred. -.RE - -.sp -.LP -The following error codes apply to \fBtnfctl_exec_open()\fR: -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_ACCES\fR\fR -.ad -.RS 28n -Permission denied. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_ALLOCFAIL\fR\fR -.ad -.RS 28n -A memory allocation failure occurred. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_NOTDYNAMIC\fR\fR -.ad -.RS 28n -The target is not a dynamic executable. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_NOLIBTNFPROBE\fR\fR -.ad -.RS 28n -\fBlibtnfprobe.so.1\fR is not linked in the target process. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_FILENOTFOUND\fR\fR -.ad -.RS 28n -The program is not found. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INTERNAL\fR\fR -.ad -.RS 28n -An internal error occurred. -.RE - -.sp -.LP -The following error codes apply to \fBtnfctl_continue()\fR: -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BADARG\fR\fR -.ad -.RS 24n -Bad input argument. \fIhndl\fR is not a direct process probe control handle. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INTERNAL\fR\fR -.ad -.RS 24n -An internal error occurred. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_NOPROCESS\fR\fR -.ad -.RS 24n -No such target process exists. -.RE - -.SH EXAMPLES -.LP -\fBExample 1 \fRUsing \fBtnfctl_pid_open()\fR -.sp -.LP -These examples do not include any error-handling code. Only the initial -example includes the declaration of the variables that are used in all of the -examples. - -.sp -.LP -The following example shows how to preload \fBlibtnfprobe.so.1\fR from the -normal location and inherit the parent's environment. - -.sp -.in +2 -.nf -const char *pgm; -char * const *argv; -tnfctl_handle_t *hndl, *new_hndl, *child_hndl; -tnfctl_errcode_t err; -char * const *envptr; -extern char **environ; -tnfctl_event_t evt; -int pid; - -/* assuming argv has been allocated */ -argv[0] = pgm; -/* set up rest of argument vector here */ -err = tnfctl_exec_open(pgm, argv, NULL, NULL, NULL, &hndl); -.fi -.in -2 - -.sp -.LP -This example shows how to preload two user-supplied libraries -\fBlibc_probe.so.1\fR and \fBlibthread_probe.so.1\fR. They interpose on the -corresponding \fBlibc.so\fR and \fBlibthread.so\fR interfaces and have probes -for function entry and exit. \fBlibtnfprobe.so.1\fR is preloaded from the -normal location and the parent's environment is inherited. - -.sp -.in +2 -.nf -/* assuming argv has been allocated */ -argv[0] = pgm; -/* set up rest of argument vector here */ -err = tnfctl_exec_open(pgm, argv, NULL, NULL, - "libc_probe.so.1 libthread_probe.so.1", &hndl); -.fi -.in -2 - -.sp -.LP -This example preloads an interposition library \fBlibc_probe.so.1\fR, and -specifies a different location from which to preload \fBlibtnfprobe.so.1\fR. - -.sp -.in +2 -.nf -/* assuming argv has been allocated */ -argv[0] = pgm; -/* set up rest of argument vector here */ -err = tnfctl_exec_open(pgm, argv, NULL, "/opt/SUNWXXX/lib", - "libc_probe.so.1", &hndl); -.fi -.in -2 - -.sp -.LP -To set up the environment explicitly for probe control to work, the target -process must link \fBlibtnfprobe.so.1\fR. If using \fIenvp\fR, it is the -caller's responsibility to do so. - -.sp -.in +2 -.nf -/* assuming argv has been allocated */ -argv[0] = pgm; -/* set up rest of argument vector here */ -/* envptr set up to caller's needs */ -err = tnfctl_exec_open(pgm, argv, envptr, NULL, NULL, &hndl); -.fi -.in -2 - -.sp -.LP -Use this example to resume a process that does an \fBexec\fR(2) without -controlling it. - -.sp -.in +2 -.nf -err = tnfctl_continue(hndl, &evt, NULL); -switch (evt) { -case TNFCTL_EVENT_EXEC: - /* let target process continue without control */ - err = tnfctl_close(hndl, TNFCTL_TARG_RESUME); - ... - break; -} -.fi -.in -2 - -.sp -.LP -Alternatively, use the next example to control a process that does an -\fBexec\fR(2). - -.sp -.in +2 -.nf -/* - * assume the pid variable has been set by calling - * tnfctl_trace_attrs_get() -*/ -err = tnfctl_continue(hndl, &evt, NULL); -switch (evt) { -case TNFCTL_EVENT_EXEC: - /* suspend the target process */ - err = tnfctl_close(hndl, TNFCTL_TARG_SUSPEND); - /* re-open the exec'ed image */ - err = tnfctl_pid_open(pid, &new_hndl); - /* new_hndl now controls the exec'ed image */ - ... - break; -} -.fi -.in -2 - -.sp -.LP -To let \fBfork\fR'ed children continue without control, use \fINULL\fR as the -last argument to \fBtnfctl_continue(\|).\fR - -.sp -.in +2 -.nf -err = tnfctl_continue(hndl, &evt, NULL); -.fi -.in -2 - -.sp -.LP -The next example is how to control child processes that \fBfork\fR(2) or -\fBfork1\fR(2) create. - -.sp -.in +2 -.nf -err = tnfctl_continue(hndl, &evt, &child_hndl); -switch (evt) { -case TNFCTL_EVENT_FORK: - /* spawn a new thread or process to control child_hndl */ - ... - break; -} -.fi -.in -2 - -.SH ATTRIBUTES -.sp -.LP -See \fBattributes\fR(7) 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), \fBproc\fR(1), \fBexec\fR(2), \fBexecve\fR(2), -\fBexit\fR(2), \fBfork\fR(2), \fBTNF_PROBE\fR(3TNF), \fBdlclose\fR(3C), -\fBdlopen\fR(3C), \fBlibtnfctl\fR(3TNF), \fBtnfctl_close\fR(3TNF), -\fBtnfctl_internal_open\fR(3TNF), \fBtracing\fR(3TNF) \fBattributes\fR(7) -.sp -.LP -\fILinker and Libraries Guide\fR -.SH NOTES -.sp -.LP -After a call to \fBtnfctl_continue()\fR returns, a client should use -\fBtnfctl_trace_attrs_get\fR(3TNF) to check the \fBtrace_buf_state\fR member of -the trace attributes and make sure that there is no internal error in the -target. diff --git a/usr/src/man/man3tnf/tnfctl_probe_apply.3tnf b/usr/src/man/man3tnf/tnfctl_probe_apply.3tnf deleted file mode 100644 index dbdb0d5ccf..0000000000 --- a/usr/src/man/man3tnf/tnfctl_probe_apply.3tnf +++ /dev/null @@ -1,229 +0,0 @@ -'\" te -.\" Copyright (c) 2004 Sun Microsystems, Inc. All Rights Reserved -.\" 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 TNFCTL_PROBE_APPLY 3TNF "Mar 1, 2004" -.SH NAME -tnfctl_probe_apply, tnfctl_probe_apply_ids \- iterate over probes -.SH SYNOPSIS -.LP -.nf -\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-ltnfctl\fR [ \fIlibrary\fR ... ] -#include <tnf/tnfctl.h> - -\fBtnfctl_errcode_t\fR \fBtnfctl_probe_apply\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR, - \fBtnfctl_probe_op_t\fR \fIprobe_op\fR, \fBvoid *\fR\fIclientdata\fR); -.fi - -.LP -.nf -\fBtnfctl_errcode_t\fR \fBtnfctl_probe_apply_ids\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR, - \fBulong_t\fR \fIprobe_count\fR, \fBulong_t *\fR\fIprobe_ids\fR, - \fBtnfctl_probe_op_t\fR \fIprobe_op\fR, \fBvoid *\fR\fIclientdata\fR); -.fi - -.SH DESCRIPTION -.sp -.LP -\fBtnfctl_probe_apply()\fR is used to iterate over the probes controlled by -\fIhndl.\fR For every probe, the \fIprobe_op\fR function is called: -.sp -.in +2 -.nf -typedef tnfctl_errcode_t (*tnfctl_probe_op_t)( - tnfctl_handle_t *hndl, - tnfctl_probe_t *probe_hndl, - void *clientdata); -.fi -.in -2 - -.sp -.LP -Several predefined functions are available for use as \fIprobe_op\fR. These -functions are described in \fBtnfctl_probe_state_get\fR(3TNF). -.sp -.LP -The \fIclientdata\fR supplied in \fBtnfctl_probe_apply()\fR is passed in as the -last argument of \fIprobe_op\fR. The \fIprobe_hndl\fR in the probe operation -function can be used to query or change the state of the probe. See -\fBtnfctl_probe_state_get\fR(3TNF). The \fIprobe_op\fR function should return -\fBTNFCTL_ERR_NONE\fR upon success. It can also return an error code, which -will cause \fBtnfctl_probe_apply()\fR to stop processing the rest of the probes -and return with the same error code. Note that there are five (5) error codes -reserved that the client can use for its own semantics. See \fBERRORS\fR. -.sp -.LP -The lifetime of \fIprobe_hndl\fR is the same as the lifetime of \fIhndl\fR. It -is good until \fIhndl\fR is closed by \fBtnfctl_close\fR(3TNF). Do not confuse -a \fIprobe_hndl\fR with \fIhndl\fR. The \fIprobe_hndl\fR refers to a particular -probe, while \fIhndl\fR refers to a process or the kernel. If \fIprobe_hndl\fR -is used in another \fBlibtnfctl\fR(3TNF) interface, and it references a probe -in a library that has been dynamically closed (see \fBdlclose\fR(3C)), then -the error code \fBTNFCTL_ERR_INVALIDPROBE\fR will be returned by that -interface. -.sp -.LP -\fBtnfctl_probe_apply_ids()\fR is very similar to \fBtnfctl_probe_apply()\fR. -The difference is that \fIprobe_op\fR is called only for probes that match a -probe id specified in the array of integers referenced by \fIprobe_ids\fR. The -number of probe ids in the array should be specified in \fIprobe_count\fR. Use -\fBtnfctl_probe_state_get()\fR to get the \fIprobe_id\fR that corresponds to -the \fIprobe_handl\fR. -.SH RETURN VALUES -.sp -.LP -\fBtnfctl_probe_apply()\fR and \fBtnfctl_probe_apply_ids()\fR return -\fBTNFCTL_ERR_NONE\fR upon success. -.SH ERRORS -.sp -.LP -The following errors apply to both \fBtnfctl_probe_apply()\fR and -\fBtnfctl_probe_apply_ids()\fR: -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INTERNAL\fR\fR -.ad -.RS 23n -An internal error occurred. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_USR1\fR\fR -.ad -.RS 23n -Error code reserved for user. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_USR2\fR\fR -.ad -.RS 23n -Error code reserved for user. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_USR3\fR\fR -.ad -.RS 23n -Error code reserved for user. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_USR4\fR\fR -.ad -.RS 23n -Error code reserved for user. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_USR5\fR\fR -.ad -.RS 23n -Error code reserved for user. -.RE - -.sp -.LP -\fBtnfctl_probe_apply()\fR and \fBtnfctl_probe_apply_ids()\fR also return any -error returned by the callback function \fIprobe_op\fR. -.sp -.LP -The following errors apply only to \fBtnfctl_probe_apply_ids()\fR: -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INVALIDPROBE\fR\fR -.ad -.RS 27n -The probe handle is no longer valid. For example, the probe is in a library -that has been closed by \fBdlclose\fR(3C). -.RE - -.SH EXAMPLES -.LP -\fBExample 1 \fREnabling Probes -.sp -.LP -To enable all probes: - -.sp -.in +2 -.nf -tnfctl_probe_apply(hndl, tnfctl_probe_enable, NULL); -.fi -.in -2 - -.LP -\fBExample 2 \fRDisabling Probes -.sp -.LP -To disable the probes that match a certain pattern in the probe attribute -string: - -.sp -.in +2 -.nf -/* To disable all probes that contain the string "vm" */ -tnfctl_probe_apply(hndl, select_disable, "vm"); -static tnfctl_errcode_t -select_disable(tnfctl_handle_t *hndl, tnfctl_probe_t *probe_hndl, -void *client_data) -{ - char *pattern = client_data; - tnfctl_probe_state_t probe_state; - tnfctl_probe_state_get(hndl, probe_hndl, &probe_state); - if (strstr(probe_state.attr_string, pattern)) { - tnfctl_probe_disable(hndl, probe_hndl, NULL); - } -} -.fi -.in -2 - -.sp -.LP -Note that these examples do not have any error handling code. - -.SH ATTRIBUTES -.sp -.LP -See \fBattributes\fR(7) 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 -.BR prex (1), -.BR dlclose (3C), -.BR dlopen (3C), -.BR TNF_PROBE (3TNF), -.BR libtnfctl (3TNF), -.BR tnfctl_close (3TNF), -.BR tnfctl_probe_state_get (3TNF), -.BR tracing (3TNF), -.BR tnf_kernel_probes (5), -.BR attributes (7) -.sp -.LP -\fILinker and Libraries Guide\fR diff --git a/usr/src/man/man3tnf/tnfctl_probe_state_get.3tnf b/usr/src/man/man3tnf/tnfctl_probe_state_get.3tnf deleted file mode 100644 index 51386d7ce0..0000000000 --- a/usr/src/man/man3tnf/tnfctl_probe_state_get.3tnf +++ /dev/null @@ -1,360 +0,0 @@ -'\" te -.\" Copyright (c) 2004 Sun Microsystems, Inc. All Rights Reserved -.\" 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 TNFCTL_PROBE_STATE_GET 3TNF "Mar 1, 2004" -.SH NAME -tnfctl_probe_state_get, tnfctl_probe_enable, tnfctl_probe_disable, -tnfctl_probe_trace, tnfctl_probe_untrace, tnfctl_probe_connect, -tnfctl_probe_disconnect_all \- interfaces to query and to change the state of a -probe -.SH SYNOPSIS -.LP -.nf -\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-ltnfctl\fR [ \fIlibrary\fR ... ] -#include <tnf/tnfctl.h> - -\fBtnfctl_errcode_t\fR \fBtnfctl_probe_state_get\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR, - \fBtnfctl_probe_t *\fR\fIprobe_hndl\fR, \fBtnfctl_probe_state_t *\fR\fIstate\fR); -.fi - -.LP -.nf -\fBtnfctl_errcode_t\fR \fBtnfctl_probe_enable\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR, - \fBtnfctl_probe_t *\fR\fIprobe_hndl\fR, \fBvoid *\fR\fIignored\fR); -.fi - -.LP -.nf -\fBtnfctl_errcode_t\fR \fBtnfctl_probe_disable\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR, - \fBtnfctl_probe_t *\fR\fIprobe_hndl\fR, \fBvoid *\fR\fIignored\fR); -.fi - -.LP -.nf -\fBtnfctl_errcode_t\fR \fBtnfctl_probe_trace\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR, - \fBtnfctl_probe_t *\fR\fIprobe_hndl\fR, \fBvoid *\fR\fIignored\fR); -.fi - -.LP -.nf -\fBtnfctl_errcode_t\fR \fBtnfctl_probe_untrace\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR, - \fBtnfctl_probe_t *\fR\fIprobe_hndl\fR, \fBvoid *\fR\fIignored\fR); -.fi - -.LP -.nf -\fBtnfctl_errcode_t\fR \fBtnfctl_probe_disconnect_all\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR, - \fBtnfctl_probe_t *\fR\fIprobe_hndl\fR, \fBvoid *\fR\fIignored\fR); -.fi - -.LP -.nf -\fBtnfctl_errcode_t\fR \fBtnfctl_probe_connect\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR, - \fBtnfctl_probe_t *\fR\fIprobe_hndl\fR, \fBconst char *\fR\fIlib_base_name\fR, - \fBconst char *\fR\fIfunc_name\fR); -.fi - -.SH DESCRIPTION -.sp -.LP -\fBtnfctl_probe_state_get()\fR returns the state of the probe specified by -\fIprobe_hndl\fR in the process or kernel specified by \fIhndl\fR. The user -will pass these in to an apply iterator. The caller must also allocate -\fIstate\fR and pass in a pointer to it. The semantics of the individual -members of \fIstate\fR are: -.sp -.ne 2 -.na -\fB\fBid\fR\fR -.ad -.RS 26n -The unique integer assigned to this probe. This number does not change over the -lifetime of this probe. A \fIprobe_hndl\fR can be obtained by using the calls -\fBtnfctl_apply()\fR, \fBtanfctl_apply_ids()\fR, or -\fBtnfctl_register_funcs()\fR. -.RE - -.sp -.ne 2 -.na -\fB\fBattr_string\fR\fR -.ad -.RS 26n -A string that consists of \fIattribute\fR \fIvalue\fR pairs separated by -semicolons. For the syntax of this string, see the syntax of the -\fBdetail\fR argument of the \fBTNF_PROBE\fR(3TNF) macro. The attributes -\fIname\fR, \fIslots\fR, \fIkeys\fR, \fBfile\fR, and \fBline\fR are defined for -every probe. Additional user-defined attributes can be added by using the -\fIdetail\fR argument of the \fBTNF_PROBE\fR(3TNF) macro. An example of -\fIattr_string\fR follows: -.sp -.in +2 -.nf -"name pageout;slots vnode pages_pageout ; -keys vm pageio io;file vm.c;line 25;" -.fi -.in -2 - -.RE - -.sp -.ne 2 -.na -\fB\fBenabled\fR\fR -.ad -.RS 26n -\fBB_TRUE\fR if the probe is enabled, or \fBB_FALSE\fR if the probe is -disabled. Probes are disabled by default. Use \fBtnfctl_probe_enable()\fR or -\fBtnfctl_probe_disable()\fR to change this state. -.RE - -.sp -.ne 2 -.na -\fB\fBtraced\fR\fR -.ad -.RS 26n -\fBB_TRUE\fR if the probe is traced, or \fBB_FALSE\fR if the probe is not -traced. Probes in user processes are traced by default. Kernel probes are -untraced by default. Use \fBtnfctl_probe_trace()\fR or -\fBtnfctl_probe_untrace()\fR to change this state. -.RE - -.sp -.ne 2 -.na -\fB\fBnew_probe\fR\fR -.ad -.RS 26n -\fBB_TRUE\fR if this is a new probe brought in since the last change in -libraries. See \fBdlopen\fR(3C) or \fBdlclose\fR(3C). Otherwise, the value of -\fBnew_probe\fR will be \fBB_FALSE\fR. This field is not meaningful for kernel -probe control. -.RE - -.sp -.ne 2 -.na -\fB\fBobj_name\fR\fR -.ad -.RS 26n -The name of the shared object or executable in which the probe is located. -This string can be freed, so the client should make a copy of the string if it -needs to be saved for use by other \fBlibtnfctl\fR interfaces. In kernel -mode, this string is always \fINULL.\fR -.RE - -.sp -.ne 2 -.na -\fB\fBfunc_names\fR\fR -.ad -.RS 26n -A null-terminated array of pointers to strings that contain the names of -functions connected to this probe. Whenever an enabled probe is encountered at -runtime, these functions are executed. This array also will be freed by the -library when the state of the probe changes. Use \fBtnfctl_probe_connect()\fR -or \fBtnfctl_probe_disconnect_all()\fR to change this state. -.RE - -.sp -.ne 2 -.na -\fB\fBfunc_addrs\fR\fR -.ad -.RS 26n -A null-terminated array of pointers to addresses of functions in the target -image connected to this probe. This array also will be freed by the library -when the state of the probe changes. -.RE - -.sp -.ne 2 -.na -\fB\fBclient_registered_data\fR\fR -.ad -.RS 26n -Data that was registered by the client for this probe by the creator function -in \fBtnfctl_register_funcs\fR(3TNF). -.RE - -.sp -.LP -\fBtnfctl_probe_enable(\|),\fR \fBtnfctl_probe_disable(\|),\fR -\fBtnfctl_probe_trace(\|),\fR \fBtnfctl_probe_untrace(\|),\fR and -\fBtnfctl_probe_disconnect_all()\fR ignore the last argument. This convenient -feature permits these functions to be used in the \fIprobe_op\fR field of -\fBtnfctl_probe_apply\fR(3TNF) and \fBtnfctl_probe_apply_ids\fR(3TNF). -\fBtnfctl_probe_enable()\fR enables the probe specified by \fIprobe_hndl\fR. -This is the master switch on a probe. A probe does not perform any action -until it is enabled. -.sp -.LP -\fBtnfctl_probe_disable()\fR disables the probe specified by \fIprobe_hndl\fR. -.sp -.LP -\fBtnfctl_probe_trace()\fR turns on tracing for the probe specified by -\fIprobe_hndl\fR. Probes emit a trace record only if the probe is traced. -.sp -.LP -\fBtnfctl_probe_untrace()\fR turns off tracing for the probe specified by -\fIprobe_hndl\fR. This is useful if you want to connect probe functions to a -probe without tracing it. -.sp -.LP -\fBtnfctl_probe_connect()\fR connects the function \fIfunc_name\fR which exists -in the library \fIlib_base_name\fR, to the probe specified by -\fIprobe_hndl\fR. \fBtnfctl_probe_connect()\fR returns an error code if used on -a kernel tnfctl handle. \fIlib_base_name\fR is the base name (not a path) of -the library. If it is \fINULL,\fR and multiple functions in the target -process match \fIfunc_name\fR, one of the matching functions is chosen -arbitrarily. A probe function is a function that is in the target's address -space and is written to a certain specification. The specification is not -currently published. -.sp -.LP -\fBtnf_probe_debug()\fR is one function exported by \fBlibtnfprobe.so.1\fR and -is the debug function that \fBprex\fR(1) uses. When the debug function is -executed, it prints out the probe arguments and the value of the -\fBsunw%debug\fR attribute of the probe to \fBstderr\fR. -.sp -.LP -\fBtnfctl_probe_disconnect_all()\fR disconnects all probe functions from the -probe specified by \fIprobe_hndl\fR. -.sp -.LP -Note that no \fBlibtnfctl\fR call returns a probe handle -(\fBtnfctl_probe_t\fR), yet each of the routines described here takes a -\fIprobe_hndl\fR as an argument. These routines may be used by passing them to -one of the \fBtnfctl_probe_apply\fR(3TNF) iterators as the "op" argument. -Alternatively, probe handles may be obtained and saved by a user's "op" -function, and they can be passed later as the \fIprobe_hndl\fR argument when -using any of the functions described here. -.SH RETURN VALUES -.sp -.LP -\fBtnfctl_probe_state_get(\|),\fR \fBtnfctl_probe_enable(\|),\fR -\fBtnfctl_probe_disable(\|),\fR \fBtnfctl_probe_trace(\|),\fR -\fBtnfctl_probe_untrace(\|),\fR \fBtnfctl_probe_disconnect_all()\fR and -\fBtnfctl_probe_connect()\fR return \fBTNFCTL_ERR_NONE\fR upon success. -.SH ERRORS -.sp -.LP -The following error codes apply to \fBtnfctl_probe_state_get()\fR: -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INVALIDPROBE\fR\fR -.ad -.RS 27n -\fIprobe_hndl\fR is no longer valid. The library that the probe was in could -have been dynamically closed by \fBdlclose\fR(3C). -.RE - -.sp -.LP -The following error codes apply to \fBtnfctl_probe_enable()\fR, -\fBtnfctl_probe_disable()\fR, \fBtnfctl_probe_trace()\fR, -\fBtnfctl_probe_untrace()\fR, and \fBtnfctl_probe_disconnect_all()\fR -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INVALIDPROBE\fR\fR -.ad -.RS 27n -\fIprobe_hndl\fR is no longer valid. The library that the probe was in could -have been dynamically closed by \fBdlclose\fR(3C). -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BUFBROKEN\fR\fR -.ad -.RS 27n -Cannot do probe operations because tracing is broken in the target. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_NOBUF\fR\fR -.ad -.RS 27n -Cannot do probe operations until a buffer is allocated. See -\fBtnfctl_buffer_alloc\fR(3TNF). This error code does not apply to kernel -probe control. -.RE - -.sp -.LP -The following error codes apply to \fBtnfctl_probe_connect()\fR: -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INVALIDPROBE\fR\fR -.ad -.RS 27n -\fIprobe_hndl\fR is no longer valid. The library that the probe was in could -have been dynamically closed by \fBdlclose\fR(3C). -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BADARG\fR\fR -.ad -.RS 27n -The handle is a kernel handle, or \fIfunc_name\fR could not be found. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BUFBROKEN\fR\fR -.ad -.RS 27n -Cannot do probe operations because tracing is broken in the target. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_NOBUF\fR\fR -.ad -.RS 27n -Cannot do probe operations until a buffer is allocated. See -\fBtnfctl_buffer_alloc\fR(3TNF). -.RE - -.SH ATTRIBUTES -.sp -.LP -See \fBattributes\fR(7) for description 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 -.BR prex (1), -.BR TNF_PROBE (3TNF), -.BR libtnfctl (3TNF), -.BR tnfctl_check_libs (3TNF), -.BR tnfctl_continue (3TNF), -.BR tnfctl_probe_apply (3TNF), -.BR tnfctl_probe_apply_ids (3TNF), -.BR tracing (3TNF), -.BR tnf_kernel_probes (5), -.BR attributes (7) diff --git a/usr/src/man/man3tnf/tnfctl_register_funcs.3tnf b/usr/src/man/man3tnf/tnfctl_register_funcs.3tnf deleted file mode 100644 index 55cb11ea8f..0000000000 --- a/usr/src/man/man3tnf/tnfctl_register_funcs.3tnf +++ /dev/null @@ -1,86 +0,0 @@ -'\" te -.\" Copyright (c) 2004 Sun Microsystems, Inc. All Rights Reserved -.\" 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 TNFCTL_REGISTER_FUNCS 3TNF "Mar 1, 2004" -.SH NAME -tnfctl_register_funcs \- register callbacks for probe creation and destruction -.SH SYNOPSIS -.LP -.nf -\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-ltnfctl\fR [ \fIlibrary\fR ... ] -#include <tnf/tnfctl.h> - -\fBtnfctl_errcode_t\fR \fBtnfctl_register_funcs\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR, \fBvoid * (*\fR\fIcreate_func\fR) - (tnfctl_handle_t *, tnfctl_probe_t *), \fBvoid (*\fR\fIdestroy_func\fR)(void *)); -.fi - -.SH DESCRIPTION -.sp -.LP -The function \fBtnfctl_register_funcs()\fR is used to store client-specific -data on a per-probe basis. It registers a creator and a destructor function -with \fIhndl\fR, either of which can be \fBNULL.\fR The creator function is -called for every probe that currently exists in \fIhndl.\fR Every time a new -probe is discovered, that is brought in by \fBdlopen\fR(3C), \fIcreate_func\fR -is called. -.sp -.LP -The return value of the creator function is stored as part of the probe state -and can be retrieved by \fBtnfctl_probe_state_get\fR(3TNF) in the member field -\fIclient_registered_data\fR. -.sp -.LP -\fIdestroy_func\fR is called for every probe handle that is freed. This does -not necessarily happen at the time \fBdlclose\fR(3C) frees the shared object. -The probe handles are freed only when \fIhndl\fR is closed by -\fBtnfctl_close\fR(3TNF). If \fBtnfctl_register_funcs()\fR is called a second -time for the same \fIhndl,\fR then the previously registered destructor -function is called first for all of the probes. -.SH RETURN VALUES -.sp -.LP -\fBtnfctl_register_funcs()\fR returns \fBTNFCTL_ERR_NONE\fR upon success. -.SH ERRORS -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INTERNAL\fR\fR -.ad -.RS 23n -An internal error occurred. -.RE - -.SH ATTRIBUTES -.sp -.LP -See \fBattributes\fR(7) 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 -.BR prex (1), -.BR dlclose (3C), -.BR dlopen (3C), -.BR TNF_PROBE (3TNF), -.BR libtnfctl (3TNF), -.BR tnfctl_close (3TNF), -.BR tnfctl_probe_state_get (3TNF), -.BR tracing (3TNF), -.BR tnf_kernel_probes (5), -.BR attributes (7) -.sp -.LP -\fILinker and Libraries Guide\fR diff --git a/usr/src/man/man3tnf/tnfctl_strerror.3tnf b/usr/src/man/man3tnf/tnfctl_strerror.3tnf deleted file mode 100644 index 651a36b6e4..0000000000 --- a/usr/src/man/man3tnf/tnfctl_strerror.3tnf +++ /dev/null @@ -1,54 +0,0 @@ -'\" te -.\" Copyright (c) 1996 Sun Microsystems, Inc. All Rights Reserved -.\" 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 TNFCTL_STRERROR 3TNF "Mar 4, 1997" -.SH NAME -tnfctl_strerror \- map a tnfctl error code to a string -.SH SYNOPSIS -.LP -.nf -\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-ltnfctl\fR [ \fIlibrary\fR ... ] -#include <tnf/tnfctl.h> - - - -\fBconst char *\fR \fBtnfctl_strerror\fR(\fBtnfctl_errcode_t\fR \fIerrcode\fR); -.fi - -.SH DESCRIPTION -.sp -.LP -\fBtnfctl_strerror()\fR maps the error number in \fIerrcode\fR to an error -message string, and it returns a pointer to that string. The returned string -should not be overwritten or freed. -.SH ERRORS -.sp -.LP -\fBtnfctl_strerror()\fR returns the string "unknown libtnfctl.so error code" if -the error number is not within the legal range. -.SH ATTRIBUTES -.sp -.LP -See \fBattributes\fR(7) 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 -.BR prex (1), -.BR TNF_PROBE (3TNF), -.BR libtnfctl (3TNF), -.BR tracing (3TNF), -.BR attributes (7) diff --git a/usr/src/man/man3tnf/tnfctl_trace_attrs_get.3tnf b/usr/src/man/man3tnf/tnfctl_trace_attrs_get.3tnf deleted file mode 100644 index f22726793a..0000000000 --- a/usr/src/man/man3tnf/tnfctl_trace_attrs_get.3tnf +++ /dev/null @@ -1,184 +0,0 @@ -'\" te -.\" Copyright (c) 1996 Sun Microsystems, Inc. All Rights Reserved -.\" 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 TNFCTL_TRACE_ATTRS_GET 3TNF "Mar 4, 1997" -.SH NAME -tnfctl_trace_attrs_get \- get the trace attributes from a tnfctl handle -.SH SYNOPSIS -.LP -.nf -\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-ltnfctl\fR [ \fIlibrary\fR... ] -#include <tnf/tnfctl.h> - -\fBtnfctl_errcode_t\fR \fBtnfctl_trace_attrs_get\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR, - \fBtnfctl_trace_attrs_t *\fR\fIattrs\fR); -.fi - -.SH DESCRIPTION -.sp -.LP -The \fBtnfctl_trace_attrs_get()\fR function returns the trace attributes -associated with \fIhndl\fR in \fIattrs\fR. The trace attributes can be changed -by some of the other interfaces in \fBlibtnfctl\fR(3TNF). It is the client's -responsibility to use \fBtnfctl_trace_attrs_get()\fR to get the new trace -attributes after use of interfaces that change them. Typically, a client will -use \fBtnfctl_trace_attrs_get()\fR after a call to \fBtnfctl_continue\fR(3TNF) -in order to make sure that tracing is still working. See the discussion of -\fBtrace_buf_state\fR that follows. -.sp -.LP -Trace attributes are represented by the \fBstruct tnfctl_trace_attrs\fR -structure defined in <\fBtnf/tnfctl.h\fR>: -.sp -.in +2 -.nf -struct tnfctl_trace_attrs { -pid_t targ_pid; /* not kernel mode */ -const char *trace_file_name; /* not kernel mode */ -size_t trace_buf_size; -size_t trace_min_size; -tnfctl_bufstate_t trace_buf_state; -boolean_t trace_state; -boolean_t filter_state; /* kernel mode only */ -long pad; -}; -.fi -.in -2 - -.sp -.LP -The semantics of the individual members of \fIattrs\fR are: -.sp -.ne 2 -.na -\fB\fBtarg_pid\fR\fR -.ad -.RS 19n -The process id of the target process. This is not valid for kernel tracing. -.RE - -.sp -.ne 2 -.na -\fB\fBtrace_file_name\fR\fR -.ad -.RS 19n -The name of the trace file to which the target writes. \fBtrace_file_name\fR -will be \fBNULL\fR if no trace file exists or if kernel tracing is implemented. -This pointer should not be used after calling other \fBlibtnfctl\fR interfaces. -The client should copy this string if it should be saved for the use of other -\fBlibtnfctl\fR interfaces. -.RE - -.sp -.ne 2 -.na -\fB\fBtrace_buf_size\fR\fR -.ad -.RS 19n -The size of the trace buffer or file in bytes. -.RE - -.sp -.ne 2 -.na -\fB\fBtrace_min_size\fR\fR -.ad -.RS 19n -The minimum size in bytes of the trace buffer that can be allocated by using -the \fBtnfctl_buffer_alloc\fR(3TNF) interface. -.RE - -.sp -.ne 2 -.na -\fB\fBtrace_buf_state\fR\fR -.ad -.RS 19n -The state of the trace buffer. \fBTNFCTL_BUF_OK\fR indicates that a trace -buffer has been allocated. \fBTNFCTL_BUF_NONE\fR indicates that no buffer has -been allocated. \fBTNFCTL_BUF_BROKEN\fR indicates that there is an internal -error in the target for tracing. The target will continue to run correctly, but -no trace records will be written. To fix tracing, restart the process. For -kernel tracing, deallocate the existing buffer with -\fBtnfctl_buffer_dealloc\fR(3TNF) and allocate a new one with -\fBtnfctl_buffer_alloc\fR(3TNF). -.RE - -.sp -.ne 2 -.na -\fB\fBtrace_state\fR\fR -.ad -.RS 19n -The global tracing state of the target. Probes that are enabled will not write -out data unless this state is on. This state is off by default for the kernel -and can be changed by \fBtnfctl_trace_state_set\fR(3TNF). For a process, this -state is on by default and can only be changed by -\fBtnf_process_disable\fR(3TNF) and \fBtnf_process_enable\fR(3TNF). -.RE - -.sp -.ne 2 -.na -\fB\fBfilter_state\fR\fR -.ad -.RS 19n -The state of process filtering. For kernel probe control, it is possible to -select a set of processes for which probes are enabled. See -\fBtnfctl_filter_list_get\fR(3TNF), \fBtnfctl_filter_list_add\fR(3TNF), and -\fBtnfctl_filter_list_delete\fR(3TNF). No trace output will be written when -other processes traverse these probe points. By default process filtering is -off, and all processes cause the generation of trace records when they hit an -enabled probe. Use \fBtnfctl_filter_state_set\fR(3TNF) to change the filter -state. -.RE - -.SH RETURN VALUES -.sp -.LP -The \fBtnfctl_trace_attrs_get()\fR function returns \fBTNFCTL_ERR_NONE\fR upon -success. -.SH ERRORS -.sp -.LP -The \fBtnfctl_trace_attrs_get()\fR function will fail if: -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INTERNAL\fR\fR -.ad -.RS 23n -An internal error occurred. -.RE - -.SH ATTRIBUTES -.sp -.LP -See \fBattributes\fR(7) 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 -.BR prex (1), -.BR TNF_PROBE (3TNF), -.BR libtnfctl (3TNF), -.BR tnf_process_disable (3TNF), -.BR tnfctl_buffer_alloc (3TNF), -.BR tnfctl_continue (3TNF), -.BR tnfctl_filter_list_get (3TNF), -.BR tracing (3TNF), -.BR attributes (7) diff --git a/usr/src/man/man3tnf/tnfctl_trace_state_set.3tnf b/usr/src/man/man3tnf/tnfctl_trace_state_set.3tnf deleted file mode 100644 index 21f927757b..0000000000 --- a/usr/src/man/man3tnf/tnfctl_trace_state_set.3tnf +++ /dev/null @@ -1,277 +0,0 @@ -'\" te -.\" Copyright (c) 1996 Sun Microsystems, Inc. All Rights Reserved -.\" 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 TNFCTL_TRACE_STATE_SET 3TNF "Mar 4, 1997" -.SH NAME -tnfctl_trace_state_set, tnfctl_filter_state_set, tnfctl_filter_list_get, -tnfctl_filter_list_add, tnfctl_filter_list_delete \- control kernel tracing and -process filtering -.SH SYNOPSIS -.LP -.nf -\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-ltnfctl\fR [ \fIlibrary\fR ... ] -#include <tnf/tnfctl.h> - -\fBtnfctl_errcode_t\fR \fBtnfctl_trace_state_set\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR, - \fBboolean_t\fR \fItrace_state\fR); -.fi - -.LP -.nf -\fBtnfctl_errcode_t\fR \fBtnfctl_filter_state_set\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR, - \fBboolean_t\fR \fIfilter_state\fR); -.fi - -.LP -.nf -\fBtnfctl_errcode_t\fR \fBtnfctl_filter_list_get\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR, - \fBpid_t **\fR\fIpid_list\fR,\ \fBint *\fR\fIpid_count\fR); -.fi - -.LP -.nf -\fBtnfctl_errcode_t\fR \fBtnfctl_filter_list_add\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR, - \fBpid_t\fR \fIpid_to_add\fR); -.fi - -.LP -.nf -\fBtnfctl_errcode_t\fR \fBtnfctl_filter_list_delete\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR, - \fBpid_t\fR \fIpid_to_delete\fR); -.fi - -.SH DESCRIPTION -.sp -.LP -The interfaces to control kernel tracing and process filtering are used only -with kernel handles, handles created by \fBtnfctl_kernel_open\fR(3TNF). These -interfaces are used to change the tracing and filter states for kernel -tracing. -.sp -.LP -\fBtnfctl_trace_state_set()\fR sets the kernel global tracing state to "on" if -\fItrace_state\fR is \fBB_TRUE,\fR or to "off" if \fItrace_state\fR is -\fBB_FALSE.\fR For the kernel, \fItrace_state\fR is off by default.Probes that -are enabled will not write out data unless this state is on. Use -\fBtnfctl_trace_attrs_get\fR(3TNF) to retrieve the current tracing state. -.sp -.LP -\fBtnfctl_filter_state_set()\fR sets the kernel process filtering state to "on" -if \fIfilter_state\fR is \fBB_TRUE,\fR or to "off" if \fIfilter_state\fR is -\fBB_FALSE.\fR \fIfilter_state\fR is off by default. If it is on, only probe -points encountered by processes in the process filter set by -\fBtnfctl_filter_list_add()\fR will generate trace points. Use -\fBtnfctl_trace_attrs_get\fR(3TNF) to retrieve the current process filtering -state. -.sp -.LP -\fBtnfctl_filter_list_get()\fR returns the process filter list as an array in -\fIpid_list\fR. The count of elements in the process filter list is returned in -\fIpid_count\fR. The caller should use \fBfree\fR(3C) to free memory allocated -for the array \fIpid_list\fR. -.sp -.LP -\fBtnfctl_filter_list_add()\fR adds \fIpid_to_add\fR to the process filter -list. The process filter list is maintained even when the process filtering -state is off, but it has no effect unless the process filtering state is on. -.sp -.LP -\fBtnfctl_filter_list_delete()\fR deletes \fIpid_to_delete\fR from the process -filter list. It returns an error if the process does not exist or is not in -the filter list. -.SH RETURN VALUES -.sp -.LP -The interfaces \fBtnfctl_trace_state_set()\fR, \fBtnfctl_filter_state_set()\fR, -\fBtnfctl_filter_list_add()\fR, \fBtnfctl_filter_list_delete()\fR, and -\fBtnfctl_filter_list_get()\fR return \fBTNFCTL_ERR_NONE\fR upon success. -.SH ERRORS -.sp -.LP -The following error codes apply to \fBtnfctl_trace_state_set\fR: -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BADARG\fR\fR -.ad -.RS 24n -The handle is not a kernel handle. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_NOBUF\fR\fR -.ad -.RS 24n -Cannot turn on tracing without a buffer being allocated. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BUFBROKEN\fR\fR -.ad -.RS 24n -Tracing is broken in the target. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INTERNAL\fR\fR -.ad -.RS 24n -An internal error occurred. -.RE - -.sp -.LP -The following error codes apply to \fBtnfctl_filter_state_set\fR: -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BADARG\fR\fR -.ad -.RS 23n -The handle is not a kernel handle. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INTERNAL\fR\fR -.ad -.RS 23n -An internal error occurred. -.RE - -.sp -.LP -The following error codes apply to \fBtnfctl_filter_list_add\fR: -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BADARG\fR\fR -.ad -.RS 24n -The handle is not a kernel handle. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_NOPROCESS\fR\fR -.ad -.RS 24n -No such process exists. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_ALLOCFAIL\fR\fR -.ad -.RS 24n -A memory allocation failure occurred. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INTERNAL\fR\fR -.ad -.RS 24n -An internal error occurred. -.RE - -.sp -.LP -The following error codes apply to \fBtnfctl_filter_list_delete\fR: -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BADARG\fR\fR -.ad -.RS 24n -The handle is not a kernel handle. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_NOPROCESS\fR\fR -.ad -.RS 24n -No such process exists. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INTERNAL\fR\fR -.ad -.RS 24n -An internal error occurred. -.RE - -.sp -.LP -The following error codes apply to \fBtnfctl_filter_list_get\fR: -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BADARG\fR\fR -.ad -.RS 24n -The handle is not a kernel handle. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_ALLOCFAIL\fR\fR -.ad -.RS 24n -A memory allocation failure occurred. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INTERNAL\fR\fR -.ad -.RS 24n -An internal error occurred. -.RE - -.SH ATTRIBUTES -.sp -.LP -See \fBattributes\fR(7) 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 -.BR prex (1), -.BR free (3C), -.BR TNF_PROBE (3TNF), -.BR libtnfctl (3TNF), -.BR tnfctl_kernel_open (3TNF), -.BR tnfctl_trace_attrs_get (3TNF), -.BR tracing (3TNF), -.BR tnf_kernel_probes (5), -.BR attributes (7) diff --git a/usr/src/man/man3tnf/tracing.3tnf b/usr/src/man/man3tnf/tracing.3tnf deleted file mode 100644 index 7fee555446..0000000000 --- a/usr/src/man/man3tnf/tracing.3tnf +++ /dev/null @@ -1,313 +0,0 @@ -'\" te -.\" Copyright (c) 1997, Sun Microsystems, Inc. -.\" All Rights Reserved -.\" 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 TRACING 3TNF "Mar 4, 1997" -.SH NAME -tracing \- overview of tnf tracing system -.SH DESCRIPTION -.sp -.LP -\fBtnf tracing\fR is a set of programs and \fBAPI's\fR that can be used to -present a high-level view of the performance of an executable, a library, or -part of the kernel. \fBtracing\fR is used to analyze a program's performance -and identify the conditions that produced a bug. -.sp -.LP -The core elements of \fBtracing\fR are: -.sp -.ne 2 -.na -\fB\fBTNF_PROBE_*(\|)\fR\fR -.ad -.RS 25n -The \fBTNF_PROBE_*(\|)\fR macros define "probes" to be placed in code which, -when enabled and executed, cause information to be added to a trace file. See -\fBTNF_PROBE\fR(3TNF). If there are insufficient \fBTNF_PROBE_*\fR macros to -store all the data of interest for a probe, data may be grouped into records. -See \fBTNF_DECLARE_RECORD\fR(3TNF). -.RE - -.sp -.ne 2 -.na -\fB\fBprex\fR\fR -.ad -.RS 25n -Displays and controls probes in running software. See prex(1). -.RE - -.sp -.ne 2 -.na -\fB\fBkernel\fR \fBprobes\fR\fR -.ad -.RS 25n -A set of probes built into the Solaris kernel which capture information about -system calls, multithreading, page faults, swapping, memory management, and -I/O. You can use these probes to obtain detailed traces of kernel activity -under your application workloads. See \fBtnf_kernel_probes\fR(5). -.RE - -.sp -.ne 2 -.na -\fB\fBtnfxtract\fR\fR -.ad -.RS 25n -A program that extracts the trace data from the kernel's in-memory buffer into -a file. See \fBtnfxtract\fR(1). -.RE - -.sp -.ne 2 -.na -\fB\fBtnfdump\fR\fR -.ad -.RS 25n -A program that displays the information from a trace file. See -\fBtnfdump\fR(1). -.RE - -.sp -.ne 2 -.na -\fB\fBlibtnfctl\fR\fR -.ad -.RS 25n -A library of interfaces that controls probes in a process. See -\fBlibtnfctl\fR(3TNF). \fBprex\fR(1) also utilizes this library. Other tools -and processes use the \fBlibtnfctl\fR interfaces to exercise fine control over -their own probes. -.RE - -.sp -.ne 2 -.na -\fB\fBtnf_process_enable()\fR\fR -.ad -.RS 25n -A routine called by a process to turn on tracing and probe functions for the -current process. See \fBtnf_process_enable\fR(3TNF). -.RE - -.sp -.ne 2 -.na -\fB\fBtnf_process_disable()\fR\fR -.ad -.RS 25n -A routine called by a process to turn off tracing and probe functions for the -current process. See \fBtnf_process_disable\fR(3TNF). -.RE - -.sp -.ne 2 -.na -\fB\fBtnf_thread_enable()\fR\fR -.ad -.RS 25n -A routine called by a process to turn on tracing and probe functions for the -currently running thread. See \fBtnf_thread_enable\fR(3TNF). -.RE - -.sp -.ne 2 -.na -\fB\fBtnf_thread_disable()\fR\fR -.ad -.RS 25n -A routine called by a process to turn off tracing and probe functions for the -currently running thread. See \fBtnf_thread_disable\fR(3TNF). -.RE - -.SH EXAMPLES -.LP -\fBExample 1 \fRTracing a Process -.sp -.LP -The following function in some daemon process accepts job requests of various -types, queueing them for later execution. There are two "debug probes" and one -"production probe." Note that probes which are intended for debugging will not -be compiled into the final version of the code; however, production probes are -compiled into the final product. - -.sp -.in +2 -.nf - /* - * To compile in all probes (for development): - * cc -DTNF_DEBUG ... - * - * To compile in only production probes (for release): - * cc ... - * - * To compile in no probes at all: - * cc -DNPROBE ... - */ -#include <tnf/probe.h> -void work(long, char *); -enum work_request_type { READ, WRITE, ERASE, UPDATE }; -static char *work_request_name[] = {"read", "write", "erase", "update"}; -main(\|) -{ - long i; - for (i = READ; i <= UPDATE; i++) - work(i, work_request_name[i]); -} -void work(long request_type, char *request_name) -{ - static long q_length; - TNF_PROBE_2_DEBUG(work_start, "work", - "XYZ%debug 'in function work'", - tnf_long, request_type_arg, request_type, - tnf_string, request_name_arg, request_name); - /* assume work request is queued for later processing */ - q_length++; - TNF_PROBE_1(work_queue, "work queue", - "XYZ%work_load heavy", - tnf_long, queue_length, q_length); - TNF_PROBE_0_DEBUG(work_end, "work", ""); -} -.fi -.in -2 - -.sp -.LP -The production probe "work_queue," which remains compiled in the code, will, -when enabled, log the length of the work queue each time a request is received. - -.sp -.LP -The debug probes "work_start" and "work_end, " which are compiled only during -the development phase, track entry to and exit from the \fBwork()\fR function -and measure how much time is spent executing it. Additionally, the debug probe -"work_start" logs the value of the two incoming arguments \fBrequest_type\fR -and \fBrequest_name\fR. The runtime overhead for disabled probes is low enough -that one can liberally embed them in the code with little impact on -performance. - -.sp -.LP -For debugging, the developer would compile with \fB-DTNF_DEBUG\fR, run the -program under control of \fBprex\fR(1), enable the probes of interest (in this -case, all probes), continue the program until exit, and dump the trace file: - -.sp -.in +2 -.nf -% cc --DTNF_DEBUG -o daemon daemon.c # compile in all probes -% prex daemon # run program under prex control -Target process stopped -Type "continue" to resume the target, "help" for help ... -prex> list probes $all # list all probes in program -<probe list output here> -prex> enable $all # enable all probes -prex> continue # let target process execute -<program output here> -prex: target process finished -% ls /tmp/trace-* # trace output is in trace-<pid> -/tmp/trace-4194 -% tnfdump /tmp/trace-4194 # get ascii output of trace file -<trace records output here> -.fi -.in -2 - -.sp -.LP -For the production version of the system, the developer simply compiles without -\fB-DTNF_DEBUG\fR\&. - -.LP -\fBExample 2 \fRTracing the Kernel -.sp -.LP -Kernel tracing is similar to tracing a process; however, there are some -differences. For instance, to trace the kernel, you need superuser privileges. -The following example uses prex(1) and traces the probes in the kernel that -capture system call information. - -.sp -.in +2 -.nf -Allocate kernel -trace buffer and capture trace data: -root# prex -k -Type "help" for help ... -prex> buffer alloc 2m # allocate kernel trace buffer -Buffer of size 2097152 bytes allocated -prex> list probes $all # list all kernel probes -<probe list output here> -prex> list probes syscall # list syscall probes - # (keys=syscall) -<syscall probes list output here> -prex> enable syscall # enable only syscall probes -prex> ktrace on # turn on kernel tracing -<Run your application in another window at this point> -prex> ktrace off # turn off kernel tracing -prex> quit # exit prex -Extract the kernel's trace buffer into a file: -root# tnfxtract /tmp/ktrace # extract kernel trace buffer -Reset kernel tracing: -root# prex -k -prex> disable $all # disable all probes -prex> untrace $all # untrace all probes -prex> buffer dealloc # deallocate kernel trace buffer -prex> quit -.fi -.in -2 - -.sp -.LP -CAUTION: Do not deallocate the trace buffer until you have extracted it into -a trace file. Otherwise, you will lose the trace data that you collected from -your experiment! - -.sp -.LP -Examine the kernel trace file: - -.sp -.in +2 -.nf -root# tnfdump /tmp/ktrace # get ascii dump of trace file -<trace records output here> -.fi -.in -2 - -.sp -.LP -\fBprex\fR can also attach to a running process, list probes, and perform a -variety of other tasks. - -.SH ATTRIBUTES -.sp -.LP -See \fBattributes\fR(7) 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 -.BR prex (1), -.BR tnfdump (1), -.BR tnfxtract (1), -.BR TNF_DECLARE_RECORD (3TNF), -.BR TNF_PROBE (3TNF), -.BR libtnfctl (3TNF), -.BR tnf_process_disable (3TNF), -.BR tnf_kernel_probes (5), -.BR attributes (7) |