1libc_db(3LIB)                 Interface Libraries                libc_db(3LIB)
2
3
4

NAME

6       libc_db - threads debugging library
7

SYNOPSIS

9       cc [ flag ... ] file ... -lc_db [ library ... ]
10       #include <proc_service.h>
11       #include <thread_db.h>
12
13

DESCRIPTION

15       The  libc_db  library  provides support for monitoring and manipulating
16       threads-related aspects of a multithreaded program. There are at  least
17       two processes involved,  the controlling process and one or more target
18       processes. The controlling process is the libc_db client,  which  links
19       with  libc_db  and  uses  libc_db  to inspect or modify threads-related
20       aspects of one or more target processes. The target processes  must  be
21       multithreaded processes that use libc. The controlling process mignt or
22       might not be multithreaded itself.
23
24
25       The most commonly anticipated use for libc_db is that  the  controlling
26       process  will be a debugger for a multithreaded program, hence the "db"
27       in libc_db.
28
29
30       The libc_db library is dependent on the internal implementation details
31       of  libc. It is a "friend" of libc in the C++ sense, which is precisely
32       the "value added" by libc_db. It encapsulates  the  knowledge  of  libc
33       internals that a debugger needs to manipulate the threads-related state
34       of a target process.
35
36
37       To be able to inspect and manipulate target  processes,  libc_db  makes
38       use of certain process control primitives that must be  provided by the
39       process using libc_db. The imported interfaces are defined in proc_ser‐
40       vice(3PROC).  In  other  words,  the controlling process is linked with
41       libc_db and calls routines in libc_db. In turn, libc_db  calls  certain
42       routines  that  it  expects  the controlling process to provide.  These
43       process control  primitives allow libc_db to:
44
45           o      Look up symbols in a target process.
46
47           o      Stop and continue individual lightweight processes  (  LWPs)
48                  within a target process.
49
50           o      Stop and continue an entire target process.
51
52           o      Read and write memory and registers in a target process.
53
54
55       Initially, a controlling process obtains a handle for a target process.
56       Through that handle it  can  then  obtain  handles  for  the  component
57       objects  of  the  target  process,  its  threads,  its  synchronization
58       objects, and its thread-specific-data keys.
59
60
61       When libc_db needs  to  return  sets  of  handles  to  the  controlling
62       process,  for  example, when returning handles for all the threads in a
63       target process, it uses an  iterator  function.  An  iterator  function
64       calls  back  a  client-specified  function  once  for each handle to be
65       returned, passing one handle back on each call to  the  callback  func‐
66       tion.  The calling function also passes another parameter to the itera‐
67       tor function,  which the iterator function passes on  to  the  callback
68       function.   This makes it easy to build a linked list of thread handles
69       for a particular target process. The additional parameter is  the  head
70       of  the  linked list, and the callback function simply inserts the cur‐
71       rent handle into the linked list.
72
73
74       Callback functions are expected to return an integer.  Iteration termi‐
75       nates early if a callback function returns a non-zero value. Otherwise,
76       iteration terminates when there are no more handles to pass back.
77

INTERFACES

79       The shared object libc_db.so.1 provides the public  interfaces  defined
80       below.  See Intro(3) for additional information on shared object inter‐
81       faces.
82
83
84
85
86       td_init                       td_log
87       td_sync_get_info              td_sync_get_stats
88       td_sync_setstate              td_sync_waiters
89       td_ta_clear_event             td_ta_delete
90       td_ta_enable_stats            td_ta_event_addr
91       td_ta_event_getmsg            td_ta_get_nthreads
92       td_ta_get_ph                  td_ta_get_stats
93       td_ta_map_addr2sync           td_ta_map_id2thr
94       td_ta_map_lwp2thr             td_ta_new
95       td_ta_reset_stats             td_ta_set_event
96       td_ta_setconcurrency          td_ta_sync_iter
97       td_ta_sync_tracking_enable    td_ta_thr_iter
98       td_ta_tsd_iter                td_thr_clear_event
99       td_thr_dbresume               td_thr_dbsuspend
100       td_thr_event_enable           td_thr_event_getmsg
101       td_thr_get_info               td_thr_getfpregs
102       td_thr_getgregs               td_thr_getxregs
103       td_thr_getxregsize            td_thr_lockowner
104       td_thr_set_event              td_thr_setfpregs
105       td_thr_setgregs               td_thr_setprio
106       td_thr_setsigpending          td_thr_setxregs
107       td_thr_sigsetmask             td_thr_sleepinfo
108       td_thr_tsd                    td_thr_validate
109
110

FILES

112       /lib/libc_db.so.1       shared object
113
114
115       /lib/64/libc_db.so.1    64-bit shared object
116
117

ATTRIBUTES

119       See attributes(5) for description of the following attributes:
120
121
122
123
124       ┌─────────────────────────────┬─────────────────────────────┐
125       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
126       ├─────────────────────────────┼─────────────────────────────┤
127       │Availability                 │SUNWcsl (32-bit)             │
128       │                             │SUNWcslx (64-bit)            │
129       ├─────────────────────────────┼─────────────────────────────┤
130       │MT-Level                     │Safe                         │
131       └─────────────────────────────┴─────────────────────────────┘
132

SEE ALSO

134       Intro(3), td_ta_new(3C_DB), attributes(5), threads(5)
135
136
137
138SunOS 5.11                        24 Mar 2004                    libc_db(3LIB)
Impressum