1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
|
'\" 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)
|
