usr/src/man/man3tnf/tnf_process_disable.3tnf

   1 '\" te
   2 .\"  Copyright 2002 Sun Microsystems Inc.
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH TNF_PROCESS_DISABLE 3TNF "Feb 5, 2002"
   7 .SH NAME
   8 tnf_process_disable, tnf_process_enable, tnf_thread_disable, tnf_thread_enable
   9 \- probe control internal interface
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-ltnfprobe\fR [ \fIlibrary\fR ... ]
  14 #include <tnf/probe.h>
  15
  16
  17
  18 \fBvoid\fR \fBtnf_process_disable\fR(\fBvoid\fR);
  19 .fi
  20
  21 .LP
  22 .nf
  23 \fBvoid\fR \fBtnf_process_enable\fR(\fBvoid\fR);
  24 .fi
  25
  26 .LP
  27 .nf
  28 \fBvoid\fR \fBtnf_thread_disable\fR(\fBvoid\fR);
  29 .fi
  30
  31 .LP
  32 .nf
  33 \fBvoid\fR \fBtnf_thread_enable\fR(\fBvoid\fR);
  34 .fi
  35
  36 .SH DESCRIPTION
  37 .sp
  38 .LP
  39 There are three levels of granularity for controlling tracing and probe
  40 functions (called probing from here on): probing for the entire process, a
  41 particular thread, and the probe itself can be disabled or enabled.  The first
  42 two (process and thread) are controlled by this interface.  The probe is
  43 controlled with the \fBprex\fR(1) utility.
  44 .sp
  45 .LP
  46 The \fBtnf_process_disable()\fR function turns off probing for the process. The
  47 default process state is to have probing enabled. The
  48 \fBtnf_process_enable()\fR function turns on probing for the process.
  49 .sp
  50 .LP
  51 The \fBtnf_thread_disable()\fR function turns off probing for the currently
  52 running thread. Threads are "born" or created with this state enabled. The
  53 \fBtnf_thread_enable()\fR function turns on probing for the currently running
  54 thread.  If the program is a non-threaded program, these two thread interfaces
  55 disable or enable probing for the process.
  56 .SH ATTRIBUTES
  57 .sp
  58 .LP
  59 See \fBattributes\fR(5) for descriptions of the following attributes:
  60 .sp
  61
  62 .sp
  63 .TS
  64 box;
  65 c | c
  66 l | l .
  67 ATTRIBUTE TYPE  ATTRIBUTE VALUE
  68 _
  69 Interface Stability     Unstable
  70 _
  71 MT-Level        MT-Safe
  72 .TE
  73
  74 .SH SEE ALSO
  75 .sp
  76 .LP
  77 \fBprex\fR(1), \fBtnfdump\fR(1), \fBTNF_DECLARE_RECORD\fR(3TNF),
  78 \fBTNF_PROBE\fR(3TNF), \fBattributes\fR(5)
  79 .SH NOTES
  80 .sp
  81 .LP
  82 A probe is considered enabled only if:
  83 .RS +4
  84 .TP
  85 .ie t \(bu
  86 .el o
  87 \fBprex\fR(1) has enabled the probe AND
  88 .RE
  89 .RS +4
  90 .TP
  91 .ie t \(bu
  92 .el o
  93 the process has probing enabled, which is the default or could be set with
  94 \fBtnf_process_enable()\fR AND
  95 .RE
  96 .RS +4
  97 .TP
  98 .ie t \(bu
  99 .el o
 100 the thread that hits the probe has probing enabled, which is every thread's
 101 default or could be set with \fBtnf_thread_enable()\fR.
 102 .RE
 103 .sp
 104 .LP
 105 There is a run time cost associated with determining that the probe is
 106 disabled.  To reduce the performance effect of probes, this cost should be
 107 minimized.  The quickest way that a probe can be determined to be disabled is
 108 by the enable control that \fBprex\fR(1) uses.  Therefore, to disable all the
 109 probes in a process use the \fBdisable\fR command in \fBprex\fR(1) rather than
 110 \fBtnf_process_disable()\fR.
 111 .sp
 112 .LP
 113 The \fBtnf_process_disable()\fR and \fBtnf_process_enable()\fR functions should
 114 only be used to toggle probing based on some internal program condition. The
 115 \fBtnf_thread_disable()\fR function should be used to turn off probing for
 116 threads that are uninteresting.