TNFCTL_TRACE_ATTRS_GET(3TNF) TNF Library Functions TNFCTL_TRACE_ATTRS_GET(3TNF)


NAME


tnfctl_trace_attrs_get - get the trace attributes from a tnfctl handle

SYNOPSIS


cc [ flag... ] file... -ltnfctl [ library... ]
#include <tnf/tnfctl.h>

tnfctl_errcode_t tnfctl_trace_attrs_get(tnfctl_handle_t *hndl,
tnfctl_trace_attrs_t *attrs);


DESCRIPTION


The tnfctl_trace_attrs_get() function returns the trace attributes
associated with hndl in attrs. The trace attributes can be changed by
some of the other interfaces in libtnfctl(3TNF). It is the client's
responsibility to use tnfctl_trace_attrs_get() to get the new trace
attributes after use of interfaces that change them. Typically, a client
will use tnfctl_trace_attrs_get() after a call to tnfctl_continue(3TNF)
in order to make sure that tracing is still working. See the discussion
of trace_buf_state that follows.


Trace attributes are represented by the struct tnfctl_trace_attrs
structure defined in <tnf/tnfctl.h>:

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;
};


The semantics of the individual members of attrs are:

targ_pid
The process id of the target process. This is not
valid for kernel tracing.


trace_file_name
The name of the trace file to which the target writes.
trace_file_name will be NULL if no trace file exists
or if kernel tracing is implemented. This pointer
should not be used after calling other libtnfctl
interfaces. The client should copy this string if it
should be saved for the use of other libtnfctl
interfaces.


trace_buf_size
The size of the trace buffer or file in bytes.


trace_min_size
The minimum size in bytes of the trace buffer that can
be allocated by using the tnfctl_buffer_alloc(3TNF)
interface.


trace_buf_state
The state of the trace buffer. TNFCTL_BUF_OK indicates
that a trace buffer has been allocated.
TNFCTL_BUF_NONE indicates that no buffer has been
allocated. TNFCTL_BUF_BROKEN 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 tnfctl_buffer_dealloc(3TNF) and allocate a
new one with tnfctl_buffer_alloc(3TNF).


trace_state
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 tnfctl_trace_state_set(3TNF). For a
process, this state is on by default and can only be
changed by tnf_process_disable(3TNF) and
tnf_process_enable(3TNF).


filter_state
The state of process filtering. For kernel probe
control, it is possible to select a set of processes
for which probes are enabled. See
tnfctl_filter_list_get(3TNF),
tnfctl_filter_list_add(3TNF), and
tnfctl_filter_list_delete(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
tnfctl_filter_state_set(3TNF) to change the filter
state.


RETURN VALUES


The tnfctl_trace_attrs_get() function returns TNFCTL_ERR_NONE upon
success.

ERRORS


The tnfctl_trace_attrs_get() function will fail if:

TNFCTL_ERR_INTERNAL
An internal error occurred.


ATTRIBUTES


See attributes(5) for descriptions of the following attributes:


+---------------+-----------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+-----------------+
|MT Level | MT-Safe |
+---------------+-----------------+

SEE ALSO


prex(1), TNF_PROBE(3TNF), libtnfctl(3TNF), tnfctl_buffer_alloc(3TNF),
tnfctl_continue(3TNF), tnfctl_filter_list_get(3TNF),
tnf_process_disable(3TNF), tracing(3TNF), attributes(5)


March 4, 1997 TNFCTL_TRACE_ATTRS_GET(3TNF)