tnfctl_trace_state_set(3TNF)				       TNF Library Functions				      tnfctl_trace_state_set(3TNF)

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

SYNOPSIS

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

       tnfctl_errcode_t tnfctl_trace_state_set(tnfctl_handle_t *hndl, boolean_t trace_state);

       tnfctl_errcode_t tnfctl_filter_state_set(tnfctl_handle_t *hndl, boolean_t filter_state);

       tnfctl_errcode_t tnfctl_filter_list_get(tnfctl_handle_t *hndl, pid_t **pid_list, int *pid_count);

       tnfctl_errcode_t tnfctl_filter_list_add(tnfctl_handle_t *hndl, pid_t pid_to_add);

       tnfctl_errcode_t tnfctl_filter_list_delete(tnfctl_handle_t *hndl, pid_t pid_to_delete);

DESCRIPTION

       The interfaces to control kernel tracing and process  filtering	are  used  only  with  kernel  handles,  handles  created  by  tnfctl_ker-
       nel_open(3TNF). These interfaces are used to change the tracing and filter  states for kernel tracing.

       tnfctl_trace_state_set()  sets the kernel global tracing state to "on" if trace_state is B_TRUE, or to "off" if trace_state is B_FALSE. For
       the kernel,  trace_state is  off  by  default.	Probes	that  are  enabled  will  not  write  out  data  unless  this  state  is  on.  Use
       tnfctl_trace_attrs_get(3TNF) to retrieve the current tracing state.

       tnfctl_filter_state_set()  sets	the  kernel  process  filtering  state	to  "on" if filter_state is B_TRUE, or to "off" if filter_state is
       B_FALSE. filter_state is off by default.  If it is on, only probe points encountered  by processes in the process filter set by tnfctl_fil-
       ter_list_add() will generate trace points.  Use tnfctl_trace_attrs_get(3TNF) to retrieve the current process filtering state.

       tnfctl_filter_list_get()  returns  the  process	filter	list  as an array in pid_list. The count of elements in the process filter list is
       returned in pid_count. The caller should use free(3C) to free memory allocated for the array pid_list.

       tnfctl_filter_list_add() adds  pid_to_add to the process filter list.  The process filter list is maintained even when the process  filter-
       ing state is off, but it has no effect unless the process filtering state is on.

       tnfctl_filter_list_delete()  deletes  pid_to_delete from the process filter list.  It returns an error if the process does  not exist or is
       not in the filter list.

RETURN VALUES

       The interfaces tnfctl_trace_state_set(), tnfctl_filter_state_set(), tnfctl_filter_list_add(), tnfctl_filter_list_delete(), and  tnfctl_fil-
       ter_list_get() return TNFCTL_ERR_NONE upon success.

ERRORS

       The following error codes apply to tnfctl_trace_state_set:

       TNFCTL_ERR_BADARG	       The handle is not a kernel handle.

       TNFCTL_ERR_NOBUF 	       Cannot turn on tracing without a buffer being allocated.

       TNFCTL_ERR_BUFBROKEN	       Tracing is broken in the target.

       TNFCTL_ERR_INTERNAL	       An internal error occurred.

       The following error codes apply to tnfctl_filter_state_set:

       TNFCTL_ERR_BADARG	       The handle is not a kernel handle.

       TNFCTL_ERR_INTERNAL	       An internal error occurred.

       The following error codes apply to tnfctl_filter_list_add:

       TNFCTL_ERR_BADARG	       The handle is not a kernel handle.

       TNFCTL_ERR_NOPROCESS	       No such process exists.

       TNFCTL_ERR_ALLOCFAIL	       A memory allocation failure occurred.

       TNFCTL_ERR_INTERNAL	       An internal error occurred.

       The following error codes apply to tnfctl_filter_list_delete:

       TNFCTL_ERR_BADARG	       The handle is not a kernel handle.

       TNFCTL_ERR_NOPROCESS	       No such process exists.

       TNFCTL_ERR_INTERNAL	       An internal error occurred.

       The following error codes apply to  tnfctl_filter_list_get:

       TNFCTL_ERR_BADARG	       The handle is not a kernel handle.

       TNFCTL_ERR_ALLOCFAIL	       A memory allocation failure occurred.

       TNFCTL_ERR_INTERNAL	       An internal error occurred.

ATTRIBUTES

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

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

SEE ALSO

       prex(1),  TNF_PROBE(3TNF),  free(3C),  libtnfctl(3TNF),	tnfctl_kernel_open(3TNF),  tnfctl_trace_attrs_get(3TNF), tracing(3TNF), tnf_ker-
       nel_probes(4), attributes(5)

SunOS 5.10							    4 Mar 1997					      tnfctl_trace_state_set(3TNF)