Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
libtnfctl(3TNF)		     TNF Library Functions	       libtnfctl(3TNF)

       libtnfctl - library for TNF probe control in a process or the kernel

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

       The  libtnfctl  library provides	an  API	to control  TNF	("Trace	Normal
       Form") probes within a process or the kernel.  See tracing(3TNF)	for an
       overview	 of  the Solaris tracing architecture. The client of libtnfctl
       controls	probes in one of four modes:

       internal	mode   The target is the controlling process itself; that  is,
		       the client controls its own probes.

       direct mode     The  target  is a separate process; a client can	either
		       exec(2) a program or attach to a	 running  process  for
		       probe  control.	The  libtnfctl library uses proc(4) on
		       the target process for probe  and  process  control  in
		       this mode, and additionally provides basic process con-
		       trol features.

       indirect	mode   The target is a separate	process, but  the  controlling
		       process is already using	proc(4)	to control the target,
		       and hence  libtnfctl cannot use	those  interfaces  di-
		       rectly.	 Use this mode to control probes from within a
		       debugger. In this mode, the client must provide	a  set
		       of functions that libtnfctl can use to query and	update
		       the target process.

       kernel mode     The target is the Solaris kernel.

       A process is controlled "externally" if it is being controlled  in  ei-
       ther  direct  mode  or  indirect	mode. Alternatively, a process is con-
       trolled "internally" when it uses internal  mode	 to  control  its  own

       There  can  be only one client at a time	doing probe control on a given
       process.	Therefore, it is not possible for a process to	be  controlled
       internally while	it is being controlled externally. It is also not pos-
       sible to	have a process controlled by multiple external processes. Sim-
       ilarly, there can be only one process at	a time doing kernel probe con-
       trol. Note, however, that while a given target may only	be  controlled
       by  one libtnfctl client, a single client may control an	arbitrary num-
       ber of targets. That is,	it is possible for a process to	simultaneously
       control	its  own  probes, probes in other processes, and probes	in the

       The following tables denotes the	modes applicable to all	libtnfctl  in-
       terfaces	 (INT =	internal mode; D = direct mode;	IND = indirect mode; K
       = kernel	mode).

       These interfaces	create handles in the specified	modes:

       tnfctl_internal_open()	   INT
       tnfctl_exec_open()		     D
       tnfctl_pid_open()		     D
       tnfctl_indirect_open()				IND
       tnfctl_kernel_open()					   K

       These interfaces	are used with the specified modes:

       tnfctl_continue()			   D
       tnfctl_probe_connect()		INT	   D	      IND
       tnfctl_probe_disconnect_all ()	INT	   D	      IND
       tnfctl_trace_attrs_get()		INT	   D	      IND	K
       tnfctl_buffer_alloc()		INT	   D	      IND	K
       tnfctl_register_funcs()		INT	   D	      IND	K
       tnfctl_probe_apply()		INT	   D	      IND	K
       tnfctl_probe_apply_ids()		INT	   D	      IND	K
       tnfctl_probe_state_get ()	INT	   D	      IND	K
       tnfctl_probe_enable()		INT	   D	      IND	K
       tnfctl_probe_disable()		INT	   D	      IND	K
       tnfctl_probe_trace()		INT	   D	      IND	K
       tnfctl_probe_untrace()		INT	   D	      IND	K
       tnfctl_check_libs()		INT	   D	      IND	K
       tnfctl_close()			INT	   D	      IND	K
       tnfctl_strerror()		INT	   D	      IND	K
       tnfctl_buffer_dealloc()						K
       tnfctl_trace_state_set()						K
       tnfctl_filter_state_set()					K
       tnfctl_filter_list_get()						K
       tnfctl_filter_list_add()						K
       tnfctl_filter_list_delete()					K

       When using libtnfctl, the first task is to create a handle for control-
       ling  probes.  The  tnfctl_internal_open() function creates an internal
       mode handle for controlling probes in the same  process,	 as  described
       above.  The  tnfctl_pid_open()  and tnfctl_exec_open() functions	create
       handles in direct mode. The tnfctl_indirect_open() function creates  an
       indirect	 mode  handle, and the tnfctl_kernel_open() function creates a
       kernel mode handle. A handle is required	for use	in  nearly  all	 other
       libtnfctl functions. The	tnfctl_close() function	releases the resources
       associated with a handle.

       The tnfctl_continue() function is used in direct	mode to	resume	execu-
       tion of the target process.

       The tnfctl_buffer_alloc() function allocates a trace file or, in	kernel
       mode, a trace buffer.

       The tnfctl_probe_apply()	and tnfctl_probe_apply_ids() functions call  a
       specified function for each probe or for	a designated set of probes.

       The  tnfctl_register_funcs()  function registers	functions to be	called
       whenever	new probes are seen or probes have disappeared,	 providing  an
       opportunity to do one-time processing for each probe.

       The  tnfctl_check_libs()	function is used primarily in indirect mode to
       check whether any new probes have appeared, that	 is,  they  have  been
       made  available by  dlopen(3C), or have disappeared, that is, they have
       disassociated from the process by dlclose(3C).

       The tnfctl_probe_enable() and tnfctl_probe_disable() functions  control
       whether the probe, when hit, will be ignored.

       The  tnfctl_probe_trace()  and tnfctl_probe_untrace() functions control
       whether an enabled probe, when hit, will	cause an entry to be  made  in
       the trace file.

       The  tnfctl_probe_connect() and tnfctl_probe_disconnect_all() functions
       control which functions,	if any,	are called when	an  enabled  probe  is

       The  tnfctl_probe_state_get()  function	returns	 information about the
       status of a probe, such as whether it is	currently enabled.

       The tnfctl_trace_attrs_get() function  returns  information  about  the
       tracing session,	such as	the  size of the trace buffer or trace file.

       The  tnfctl_strerror()  function	maps a	tnfctl error code to a string,
       for reporting purposes.

       The remaining functions apply only to kernel mode.

       The tnfctl_trace_state_set() function controls the  master  switch  for
       kernel tracing.	See prex(1) for	more details.

       The  tnfctl_filter_state_set(),	tnfctl_filter_list_get(),  tnfctl_fil-
       ter_list_add(), and tnfctl_filter_list_delete() functions allow	a  set
       of  processes to	be specified for which probes will not be ignored when
       hit. This prevents kernel activity caused  by  uninteresting  processes
       from cluttering up the kernel's trace buffer.

       The  tnfctl_buffer_dealloc() function deallocates the kernel's internal
       trace buffer.

       Upon successful completion, these functions returnTNFCTL_ERR_NONE.

       The error codes for  libtnfctl are:

       TNFCTL_ERR_ACCES		       Permission denied.

       TNFCTL_ERR_NOTARGET	       The target process completed.

       TNFCTL_ERR_ALLOCFAIL	       A memory	allocation failure occurred.

       TNFCTL_ERR_INTERNAL	       An internal error occurred.

       TNFCTL_ERR_SIZETOOSMALL	       The requested trace size	is too small.

       TNFCTL_ERR_SIZETOOBIG	       The requested trace size	is too big.

       TNFCTL_ERR_BADARG	       Bad input argument.

       TNFCTL_ERR_NOTDYNAMIC	       The target is not a dynamic executable.

       TNFCTL_ERR_NOLIBTNFPROBE not linked in target.

       TNFCTL_ERR_BUFBROKEN	       Tracing is broken in the	target.

       TNFCTL_ERR_BUFEXISTS	       A buffer	already	exists.

       TNFCTL_ERR_NOBUF		       No buffer exists.

       TNFCTL_ERR_BADDEALLOC	       Cannot deallocate buffer.

       TNFCTL_ERR_NOPROCESS	       No such target process exists.

       TNFCTL_ERR_FILENOTFOUND	       File not	found.

       TNFCTL_ERR_BUSY		       Cannot attach to	process	or kernel  be-
				       cause it	is already tracing.

       TNFCTL_ERR_INVALIDPROBE	       Probe no	longer valid.

       TNFCTL_ERR_USR1		       Error code reserved for user.

       TNFCTL_ERR_USR2		       Error code reserved for user.

       TNFCTL_ERR_USR3		       Error code reserved for user.

       TNFCTL_ERR_USR4		       Error code reserved for user.

       TNFCTL_ERR_USR5		       Error code reserved for user.

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

       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       |Availability		     |SUNWtnfc			   |
       |MT Level		     |MT-Safe with exceptions	   |

       prex(1),	exec(2), dlclose(3C), dlopen(3C), TNF_PROBE(3TNF), tnfctl_buf-
       fer_alloc(3TNF),	tnfctl_buffer_dealloc(3TNF),  tnfctl_check_libs(3TNF),
       tnfctl_close(3TNF),  tnfctl_continue(3TNF), tnfctl_internal_open(3TNF),
       tnfctl_exec_open(3TNF),	  tnfctl_filter_list_add(3TNF),	   tnfctl_fil-
       ter_list_delete(3TNF),	  tnfctl_filter_list_get(3TNF),	   tnfctl_fil-
       ter_state_set(3TNF),  tnfctl_kernel_open(3TNF),	tnfctl_pid_open(3TNF),
       tnfctl_probe_apply(3TNF),       tnfctl_probe_apply_ids(3TNF),	   tn-
       fctl_probe_connect(3TNF), tnfctl_probe_disable(3TNF),  tnfctl_probe_en-
       able(3TNF), tnfctl_probe_state_get(3TNF), tnfctl_probe_trace(3TNF), tn-
       fctl_probe_untrace(3TNF),   tnfctl_indirect_open(3TNF),	 tnfctl_regis-
       ter_funcs(3TNF),	 tnfctl_strerror(3TNF),	 tnfctl_trace_attrs_get(3TNF),
       tnfctl_trace_state_set(3TNF), libtnfctl(3LIB), proc(4), attributes(5)

       Linker and Libraries Guide

       This  API is MT-Safe.  Multiple threads may concurrently	operate	on in-
       dependent  tnfctl handles, which	is the typical behavior	expected.  The
       libtnfctl library does not support multiple threads  operating  on  the
       same  tnfctl  handle.  If this is desired, it is	the client's responsi-
       bility to implement  locking to ensure that two threads	that  use  the
       same tnfctl handle are not simultaneously in a libtnfctl	interface.

SunOS 5.10			  1 Mar	2004		       libtnfctl(3TNF)


Want to link to this manual page? Use this URL:

home | help