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

   1 '\" te
   2 .\"  Copyright (c) 1996 Sun Microsystems, Inc.  All Rights Reserved
   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 TNFCTL_TRACE_ATTRS_GET 3TNF "Mar 4, 1997"
   7 .SH NAME
   8 tnfctl_trace_attrs_get \- get the trace attributes from a tnfctl handle
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-ltnfctl\fR [ \fIlibrary\fR... ]
  13 #include <tnf/tnfctl.h>
  14
  15 \fBtnfctl_errcode_t\fR \fBtnfctl_trace_attrs_get\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR,
  16      \fBtnfctl_trace_attrs_t *\fR\fIattrs\fR);
  17 .fi
  18
  19 .SH DESCRIPTION
  20 .sp
  21 .LP
  22 The \fBtnfctl_trace_attrs_get()\fR function returns the trace attributes
  23 associated with \fIhndl\fR in \fIattrs\fR. The trace attributes can be changed
  24 by some of the other interfaces in \fBlibtnfctl\fR(3TNF). It is the client's
  25 responsibility to use  \fBtnfctl_trace_attrs_get()\fR to get  the new trace
  26 attributes after use of interfaces that change them.  Typically, a client will
  27 use \fBtnfctl_trace_attrs_get()\fR after a call to \fBtnfctl_continue\fR(3TNF)
  28 in order to make sure that tracing is still working.  See the discussion of
  29 \fBtrace_buf_state\fR that follows.
  30 .sp
  31 .LP
  32 Trace attributes are represented by the \fBstruct tnfctl_trace_attrs\fR
  33 structure defined in <\fBtnf/tnfctl.h\fR>:
  34 .sp
  35 .in +2
  36 .nf
  37 struct tnfctl_trace_attrs {
  38 pid_t              targ_pid;           /* not kernel mode */
  39 const char         *trace_file_name;   /* not kernel mode */
  40 size_t             trace_buf_size;
  41 size_t             trace_min_size;
  42 tnfctl_bufstate_t  trace_buf_state;
  43 boolean_t          trace_state;
  44 boolean_t          filter_state;       /* kernel mode only */
  45 long               pad;
  46 };
  47 .fi
  48 .in -2
  49
  50 .sp
  51 .LP
  52 The semantics of the individual members of \fIattrs\fR are:
  53 .sp
  54 .ne 2
  55 .na
  56 \fB\fBtarg_pid\fR\fR
  57 .ad
  58 .RS 19n
  59 The process id of the target process.  This is not valid for kernel tracing.
  60 .RE
  61
  62 .sp
  63 .ne 2
  64 .na
  65 \fB\fBtrace_file_name\fR\fR
  66 .ad
  67 .RS 19n
  68 The name of the trace file to which the target writes.  \fBtrace_file_name\fR
  69 will be \fBNULL\fR if no trace file exists or if kernel tracing is implemented.
  70 This pointer should not be used after calling other \fBlibtnfctl\fR interfaces.
  71 The client should copy this string if it should be saved for the use of other
  72 \fBlibtnfctl\fR interfaces.
  73 .RE
  74
  75 .sp
  76 .ne 2
  77 .na
  78 \fB\fBtrace_buf_size\fR\fR
  79 .ad
  80 .RS 19n
  81 The size of the trace buffer or file in bytes.
  82 .RE
  83
  84 .sp
  85 .ne 2
  86 .na
  87 \fB\fBtrace_min_size\fR\fR
  88 .ad
  89 .RS 19n
  90 The minimum size in bytes of the trace buffer that can be allocated by using
  91 the \fBtnfctl_buffer_alloc\fR(3TNF) interface.
  92 .RE
  93
  94 .sp
  95 .ne 2
  96 .na
  97 \fB\fBtrace_buf_state\fR\fR
  98 .ad
  99 .RS 19n
 100 The state of the trace buffer. \fBTNFCTL_BUF_OK\fR indicates that a trace
 101 buffer has been allocated. \fBTNFCTL_BUF_NONE\fR indicates that no buffer has
 102 been allocated. \fBTNFCTL_BUF_BROKEN\fR indicates that there is an internal
 103 error in the target for tracing. The target will continue to run correctly, but
 104 no trace records will be written. To fix tracing, restart the process. For
 105 kernel tracing, deallocate the existing buffer with
 106 \fBtnfctl_buffer_dealloc\fR(3TNF) and allocate a new one with
 107 \fBtnfctl_buffer_alloc\fR(3TNF).
 108 .RE
 109
 110 .sp
 111 .ne 2
 112 .na
 113 \fB\fBtrace_state\fR\fR
 114 .ad
 115 .RS 19n
 116 The global tracing state of the target. Probes that are enabled will not  write
 117 out data unless this state is on. This state is off by default for the kernel
 118 and can be changed by \fBtnfctl_trace_state_set\fR(3TNF). For a process, this
 119 state is on by default and can only be changed by
 120 \fBtnf_process_disable\fR(3TNF) and  \fBtnf_process_enable\fR(3TNF).
 121 .RE
 122
 123 .sp
 124 .ne 2
 125 .na
 126 \fB\fBfilter_state\fR\fR
 127 .ad
 128 .RS 19n
 129 The state of process filtering.  For kernel probe control, it is possible to
 130 select a set of processes for which probes are enabled. See
 131 \fBtnfctl_filter_list_get\fR(3TNF), \fBtnfctl_filter_list_add\fR(3TNF), and
 132 \fBtnfctl_filter_list_delete\fR(3TNF). No trace output will be written when
 133 other processes traverse these probe points.  By default process filtering is
 134 off, and all processes cause the generation of trace records when they hit an
 135 enabled probe.  Use \fBtnfctl_filter_state_set\fR(3TNF) to change the filter
 136 state.
 137 .RE
 138
 139 .SH RETURN VALUES
 140 .sp
 141 .LP
 142 The \fBtnfctl_trace_attrs_get()\fR function returns \fBTNFCTL_ERR_NONE\fR upon
 143 success.
 144 .SH ERRORS
 145 .sp
 146 .LP
 147 The \fBtnfctl_trace_attrs_get()\fR function will fail if:
 148 .sp
 149 .ne 2
 150 .na
 151 \fB\fBTNFCTL_ERR_INTERNAL\fR\fR
 152 .ad
 153 .RS 23n
 154 An internal error occurred.
 155 .RE
 156
 157 .SH ATTRIBUTES
 158 .sp
 159 .LP
 160 See \fBattributes\fR(5) for descriptions of the following attributes:
 161 .sp
 162
 163 .sp
 164 .TS
 165 box;
 166 c | c
 167 l | l .
 168 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 169 _
 170 MT Level        MT-Safe
 171 .TE
 172
 173 .SH SEE ALSO
 174 .sp
 175 .LP
 176 \fBprex\fR(1), \fBTNF_PROBE\fR(3TNF), \fBlibtnfctl\fR(3TNF),
 177 \fBtnfctl_buffer_alloc\fR(3TNF), \fBtnfctl_continue\fR(3TNF),
 178 \fBtnfctl_filter_list_get\fR(3TNF), \fBtnf_process_disable\fR(3TNF),
 179 \fBtracing\fR(3TNF), \fBattributes\fR(5)