Interface Libraries                                 libcdb(3LIB)



NAME
     libcdb - threads debugging library

SYNOPSIS
     cc [ flag ... ] file ... -lcdb [ library ... ]
     #include 
     #include 


DESCRIPTION
     The libcdb library  provides  support  for  monitoring  and
     manipulating threads-related aspects of a multithreaded pro-
     gram. There are at least two processes involved,   the  con-
     trolling  process and one or more target processes. The con-
     trolling process is the libcdb  client,  which  links  with
     libcdb  and  uses  libcdb  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 libcdb  is  that  the
     controlling  process  will be a debugger for a multithreaded
     program, hence the "db" in libcdb.


     The libcdb library is dependent on the internal implementa-
     tion  details  of  libc. It is a "friend" of libc in the C]
     sense, which is precisely the "value added" by  libcdb.  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,
     libcdb makes use of certain process control primitives that
     must be  provided by the process using libcdb. The imported
     interfaces  are  defined  in  procservice(3PROC).  In other
     words, the controlling process is linked  with  libcdb  and
     calls  routines  in  libcdb. In turn, libcdb calls certain
     routines that it expects the controlling process to provide.
     These process control  primitives allow libcdb 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



SunOS 5.11          Last change: 24 Mar 2004                    1






Interface Libraries                                 libcdb(3LIB)



              process.


     Initially, a controlling process obtains a handle for a tar-
     get  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 libcdb needs to return sets of handles to the control-
     ling  process,  for  example, when returning handles for all
     the threads in a target process, it uses an  iterator  func-
     tion.  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 cal-
     ling function also passes another parameter to the  iterator
     function,   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. Otherwise, iteration terminates  when  there
     are no more handles to pass back.

INTERFACES
     The shared object libcdb.so.1 provides  the  public  inter-
     faces defined below. See Intro(3) for additional information
     on shared object interfaces.



     tdinit                       tdlog
     tdsyncgetinfo              tdsyncgetstats
     tdsyncsetstate              tdsyncwaiters
     tdtaclearevent             tdtadelete
     tdtaenablestats            tdtaeventaddr
     tdtaeventgetmsg            tdtagetnthreads
     tdtagetph                  tdtagetstats
     tdtamapaddr2sync           tdtamapid2thr
     tdtamaplwp2thr             tdtanew
     tdtaresetstats             tdtasetevent
     tdtasetconcurrency          tdtasynciter
     tdtasynctrackingenable    tdtathriter
     tdtatsditer                tdthrclearevent
     tdthrdbresume               tdthrdbsuspend
     tdthreventenable           tdthreventgetmsg



SunOS 5.11          Last change: 24 Mar 2004                    2






Interface Libraries                                 libcdb(3LIB)



     tdthrgetinfo               tdthrgetfpregs
     tdthrgetgregs               tdthrgetxregs
     tdthrgetxregsize            tdthrlockowner
     tdthrsetevent              tdthrsetfpregs
     tdthrsetgregs               tdthrsetprio
     tdthrsetsigpending          tdthrsetxregs
     tdthrsigsetmask             tdthrsleepinfo
     tdthrtsd                    tdthrvalidate


FILES
     /lib/libcdb.so.1       shared object


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


ATRIBUTES
     See attributes(5) for description of  the  following  attri-
     butes:



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     Availability                 SUNWcsl (32-bit)            
                                  SUNWcslx (64-bit)           
    
     MT-Level                     Safe                        
    


SEE ALSO
     Intro(3), tdtanew(3CDB), attributes(5), threads(5)




















SunOS 5.11          Last change: 24 Mar 2004                    3