1td_sync_get_info(3C_DB)Threads Debugging Library Functiontsd_sync_get_info(3C_DB)
2
3
4

NAME

6       td_sync_get_info,     td_ta_sync_tracking_enable,    td_sync_get_stats,
7       td_sync_setstate, td_sync_waiters -  operations  on  a  synchronization
8       object in libc_db
9

SYNOPSIS

11       cc [ flag... ] file... -lc_db [ library... ]
12       #include <proc_service.h>
13       #include <thread_db.h>
14
15       td_err_e td_sync_get_info(const td_synchandle_t *sh_p, td_syncinfo_t *si_p);
16
17
18       td_err_e td_ta_sync_tracking_enable(const td_thragent_t *ta_p, int on_off);
19
20
21       td_err_e td_sync_get_stats(const td_synchandle_t *sh_p, td_syncstats_t *ss_p);
22
23
24       td_err_e td_sync_setstate(const td_synchandle_t *sh_p);
25
26
27       typedef int td_thr_iter_f(const td_thrhandle_t *th_p, void *cb_data_p);
28
29
30       td_err_e td_sync_waiters(const td_synchandle_t *sh_p, td_thr_iter_f *cb,
31            void *cb_data_p);
32
33

DESCRIPTION

35       Synchronization  objects  include  mutexes,  condition variables, sema‐
36       phores, and reader-writer locks. In the same way that thread operations
37       use  a thread handle of type td_thrhandle_t, operations on synchroniza‐
38       tion objects use a synchronization object handle  of  type  td_synchan‐
39       dle_t.
40
41
42       The  controlling  process obtains synchronization object handles either
43       by calling the function td_ta_sync_iter() to  obtain  handles  for  all
44       synchronization  objects  of  the  target process that are known to the
45       libc_db library of interfaces, or by mapping the address of a  synchro‐
46       nization  object in the address space of the target process to a handle
47       by calling td_ta_map_addr2sync(3C_DB).
48
49
50       Not all synchronization objects that a process uses can be known to the
51       libc_db  library and returned by td_ta_sync_iter(3C_DB). A synchroniza‐
52       tion object is known to libc_db only if it has been  the  target  of  a
53       synchronization   primitive  in  the  process  (such  as  mutex_lock(),
54       described on the mutex_init(3C) manual page) after td_ta_new(3C_DB) has
55       been  called  to attach to the process and td_ta_sync_tracking_enable()
56       has been called to enable synchronization object tracking.
57
58
59       The td_ta_sync_tracking_enable() function turns synchronization  object
60       tracking  on  or  off  for the process identified by ta_p, depending on
61       whether on_off is 0 (off) or non-zero (on).
62
63
64       The td_sync_get_info() function fills in  the  td_syncinfo_t  structure
65       *si_p  with  values for the synchronization object identified by  sh_p.
66       The td_syncinfo_t structure contains the following fields:
67
68       td_thragent_t *si_ta_p       The internal  process  handle  identifying
69                                    the target process through which this syn‐
70                                    chronization object handle  was  obtained.
71                                    Synchronization  objects  may  be process-
72                                    private or process-shared. In  the  latter
73                                    case,  the same synchronization object may
74                                    have multiple handles, one for each target
75                                    process's  "view"  of  the synchronization
76                                    object.
77
78
79       psaddr_t si_sv_addr          The address of the synchronization  object
80                                    in this target process's address space.
81
82
83       td_sync_type_e si_type       The  type of the synchronization variable:
84                                    mutex, condition variable,  semaphore,  or
85                                    readers-writer lock.
86
87
88       int si_shared_type           If  si_shared_type  is non-zero, this syn‐
89                                    chronization  object  is   process-shared,
90                                    otherwise it is process-private.
91
92
93       td_sync_flags_t si_flags     Flags  dependent  on  the type of the syn‐
94                                    chronization object.
95
96
97       int si_state.sema_count      Semaphores only.  The current value of the
98                                    semaphore
99
100
101       int si_state.nreaders        Readers-writer  locks  only. The number of
102                                    readers currently  holding  the  lock,  or
103                                    -1,  if  a writer is currently holding the
104                                    lock.
105
106
107       int si_state.mutex_locked    For mutexes only. Non-zero if and only  if
108                                    the mutex is currently locked.
109
110
111       int si_size                  The size of the synchronization object.
112
113
114       uint8_t si_has_waiters       Non-zero  if  and  only  if  at  least one
115                                    thread is blocked on this  synchronization
116                                    object.
117
118
119       uint8_t si_is_wlocked        For reader-writer locks only. The value is
120                                    non-zero if and only if this lock is  held
121                                    by a writer.
122
123
124       uint8_t si_rcount            PTHREAD_MUTEX_RECURSIVE  mutexes  only. If
125                                    the mutex is held, the recursion count.
126
127
128       uint8_t si_prioceiling       PTHREAD_PRIO_PROTECT   protocol    mutexes
129                                    only. The priority ceiling.
130
131
132       td_thrhandle_t si_owner      Mutexes  and  readers-writer  locks  only.
133                                    This is the thread holding the  mutex,  or
134                                    the write lock, if this is a reader-writer
135                                    lock. The value is    NULL if no one holds
136                                    the mutex or write-lock.
137
138
139       pid_t si_ownerpid            Mutexes only.  For a locked process-shared
140                                    mutex,  this  is  the  process-ID  of  the
141                                    process containing the owning thread.
142
143
144
145       The  td_sync_get_stats() function fills in the td_syncstats_t structure
146       *ss_p with values for the synchronization object  identified  by  sh_p.
147       The  td_syncstats_t structure contains an embedded td_syncinfo_t struc‐
148       ture that is filled in as described above for  td_sync_get_info().   In
149       addition,  usage statistics gathered since td_ta_sync_tracking_enable()
150       was called to enable synchronization object tracking  are  returned  in
151       the ss_un.mutex, ss_un.cond, ss_un.rwlock, or ss_un.sema members of the
152       td_syncstats_t structure, depending on the type of the  synchronization
153       object.
154
155
156       The  td_sync_setstate  function  modifies  the state of synchronization
157       object si_p, depending on the synchronization object type. For mutexes,
158       td_sync_setstate  is  unlocked  if  the  value  is   0. Otherwise it is
159       locked. For semaphores, the semaphore's count is set to the value.  For
160       reader-writer  locks, the reader count set to the value if value is >0.
161       The count is set to write-locked if value is -1. It is set to  unlocked
162       if  the value is  0. Setting the state of a synchronization object from
163       a libc_db interface may cause the synchronization object's semantics to
164       be  violated  from  the  point  of  view  of  the threads in the target
165       process. For example, if a thread holds a mutex,  and  td_sync_setstate
166       is  used  to  set  the mutex to unlocked, then a different thread  will
167       also be able to subsequently acquire the same mutex.
168
169
170       The td_sync_waiters function iterates over the set of thread handles of
171       threads  blocked  on  sh_p. The callback function cb is called once for
172       each  such  thread  handle,  and  is  passed   the  thread  handle  and
173       cb_data_p. If the callback function returns a non-zero value, iteration
174       is terminated early. See td_ta_thr_iter(3C_DB).
175

RETURN VALUES

177       TD_OK        The call returned successfully.
178
179
180       TD_BADTH     An invalid thread handle was passed in.
181
182
183       TD_DBERR     A call to one of the imported interface routines failed.
184
185
186       TD_ERR       A libc_db-internal error occurred.
187
188

ATTRIBUTES

190       See attributes(5) for descriptions of the following attributes:
191
192
193
194
195       ┌─────────────────────────────┬─────────────────────────────┐
196       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
197       ├─────────────────────────────┼─────────────────────────────┤
198       │MT-Level                     │Safe                         │
199       └─────────────────────────────┴─────────────────────────────┘
200

SEE ALSO

202       libc_db(3LIB),       mutex_init(3C),        td_ta_map_addr2sync(3C_DB),
203       td_ta_sync_iter(3C_DB), td_ta_thr_iter(3C_DB), attributes(5)
204
205
206
207SunOS 5.11                        5 Jun 2007           td_sync_get_info(3C_DB)
Impressum