Manual Pages for UNIX Operating System command usage for man libc_db

Interface Libraries                                 libc_db(3LIB)



NAME
     libc_db - threads debugging library

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


DESCRIPTION
     The libc_db 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 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 implementa-
     tion  details  of  libc. It is a "friend" of libc in the C++
     sense, which is precisely 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



SunOS 5.11          Last change: 24 Mar 2004                    1






Interface Libraries                                 libc_db(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 libc_db 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 libc_db.so.1 provides  the  public  inter-
     faces 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



SunOS 5.11          Last change: 24 Mar 2004                    2






Interface Libraries                                 libc_db(3LIB)



     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  attri-
     butes:



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Availability                | system/library (32-bit)     |
    |                             | SUNWcslx (64-bit)           |
    |_____________________________|_____________________________|
    | MT-Level                    | Safe                        |
    |_____________________________|_____________________________|


SEE ALSO
     Intro(3), td_ta_new(3C_DB), attributes(5), threads(5)




















SunOS 5.11          Last change: 24 Mar 2004                    3