libc_db(3LIB)							Interface Libraries						     libc_db(3LIB)

NAME

       libc_db - threads debugging library

SYNOPSIS

       cc [ flag ... ] file ... -lc_db [ library ... ]
       #include <proc_service.h>
       #include <thread_db.h>

DESCRIPTION

       The libc_db library provides support for monitoring and manipulating threads-related aspects of a multithreaded program. There are at least
       two processes involved,	the controlling process and one or more target processes. The controlling process is  the  libc_db  client,  which
       links with libc_db and uses libc_db to inspect or modify threads-related aspects of one or more target processes. The target processes must
       be multithreaded processes that use libc. The controlling process mignt or might not be multithreaded itself.

       The most commonly anticipated use for libc_db is that the controlling process will be a debugger for a  multithreaded  program,	hence  the
       "db" in libc_db.

       The  libc_db  library is dependent on the internal implementation details of libc. It is a "friend" of libc in the C++ sense, which is pre-
       cisely the "value added" by libc_db. It encapsulates the knowledge of libc internals that a  debugger  needs  to  manipulate  the  threads-
       related state of a target process.

       To  be  able  to inspect and manipulate target processes, libc_db makes use of certain process control primitives that must be  provided by
       the process using libc_db. The imported interfaces are defined in proc_service(3PROC). In other words, the controlling  process	is  linked
       with  libc_db  and  calls  routines in libc_db. In turn, libc_db calls certain routines that it expects the controlling process to provide.
       These process control  primitives allow libc_db to:

	 o  Look up symbols in a target process.

	 o  Stop and continue individual lightweight processes ( LWPs) within a target process.

	 o  Stop and continue an entire target process.

	 o  Read and write memory and registers in a target process.

       Initially, a controlling process obtains a handle for a target process. Through that handle it can then obtain handles  for  the  component
       objects of the target process, its threads, its synchronization objects, and its thread-specific-data keys.

       When  libc_db needs to return sets of handles to the controlling process, for example, when returning handles for all the threads in a tar-
       get process, it uses an iterator function. An iterator function calls back a client-specified function once for each handle to be returned,
       passing	one  handle  back on each call to the callback function.  The calling function also passes another parameter to the iterator func-
       tion,  which the iterator function passes on to the callback function.  This makes it easy to build a linked list of thread handles  for  a
       particular  target  process.  The additional parameter is the head of the linked list, and the callback function simply inserts the current
       handle into the linked list.

       Callback functions are expected to return an integer.  Iteration terminates early if a callback function returns a non-zero  value.  Other-
       wise, iteration terminates when there are no more handles to pass back.

INTERFACES

       The  shared  object  libc_db.so.1  provides  the  public interfaces defined below. See intro(3) for additional information on shared object
       interfaces.

       td_init			     td_log
       td_sync_get_info 	     td_sync_get_stats
       td_sync_setstate 	     td_sync_waiters
       td_ta_clear_event	     td_ta_delete
       td_ta_enable_stats	     td_ta_event_addr
       td_ta_event_getmsg	     td_ta_get_nthreads
       td_ta_get_ph		     td_ta_get_stats
       td_ta_map_addr2sync	     td_ta_map_id2thr

       td_ta_map_lwp2thr	     td_ta_new
       td_ta_reset_stats	     td_ta_set_event
       td_ta_setconcurrency	     td_ta_sync_iter
       td_ta_sync_tracking_enable    td_ta_thr_iter
       td_ta_tsd_iter		     td_thr_clear_event
       td_thr_dbresume		     td_thr_dbsuspend
       td_thr_event_enable	     td_thr_event_getmsg
       td_thr_get_info		     td_thr_getfpregs
       td_thr_getgregs		     td_thr_getxregs
       td_thr_getxregsize	     td_thr_lockowner
       td_thr_set_event 	     td_thr_setfpregs
       td_thr_setgregs		     td_thr_setprio
       td_thr_setsigpending	     td_thr_setxregs
       td_thr_sigsetmask	     td_thr_sleepinfo
       td_thr_tsd		     td_thr_validate

FILES

       /lib/libc_db.so.1		       shared object

       /lib/64/libc_db.so.1		       64-bit shared object

ATTRIBUTES

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

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWcsl (32-bit)		   |
       +-----------------------------+-----------------------------+
       |			     |SUNWcslx (64-bit) 	   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |Safe			   |
       +-----------------------------+-----------------------------+

SEE ALSO

       intro(3), td_ta_new(3C_DB), attributes(5), threads(5)

SunOS 5.10							    24 Mar 2004 						     libc_db(3LIB)