1td_sync_get_info(3C_DB)Threads Debugging Library Functiontsd_sync_get_info(3C_DB)
2
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
11 cc [ flag... ] file... -lc_db [ library... ]
12 #include <proc_service.h>
13 #include <thread_db.h>
14 td_err_e td_sync_get_info(const td_synchandle_t *sh_p, td_syncinfo_t *si_p);
16 td_err_e td_ta_sync_tracking_enable(const td_thragent_t *ta_p, int on_off);
19 td_err_e td_sync_get_stats(const td_synchandle_t *sh_p, td_syncstats_t *ss_p);
22 td_err_e td_sync_setstate(const td_synchandle_t *sh_p);
25 typedef int td_thr_iter_f(const td_thrhandle_t *th_p, void *cb_data_p);
28 td_err_e td_sync_waiters(const td_synchandle_t *sh_p, td_thr_iter_f *cb,
31 void *cb_data_p);
32
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 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 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 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 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 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 psaddr_t si_sv_addr The address of the synchronization object
80 in this target process's address space.
81 td_sync_type_e si_type The type of the synchronization variable:
84 mutex, condition variable, semaphore, or
85 readers-writer lock.
86 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 td_sync_flags_t si_flags Flags dependent on the type of the syn‐
94 chronization object.
95 int si_state.sema_count Semaphores only. The current value of the
98 semaphore
99 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 int si_state.mutex_locked For mutexes only. Non-zero if and only if
108 the mutex is currently locked.
109 int si_size The size of the synchronization object.
112 uint8_t si_has_waiters Non-zero if and only if at least one
115 thread is blocked on this synchronization
116 object.
117 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 uint8_t si_rcount PTHREAD_MUTEX_RECURSIVE mutexes only. If
125 the mutex is held, the recursion count.
126 uint8_t si_prioceiling PTHREAD_PRIO_PROTECT protocol mutexes
129 only. The priority ceiling.
130 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 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 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 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 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
177 TD_OK The call returned successfully.
178 TD_BADTH An invalid thread handle was passed in.
181 TD_DBERR A call to one of the imported interface routines failed.
184 TD_ERR A libc_db-internal error occurred.
187
190 See attributes(5) for descriptions of the following attributes:
191 ┌─────────────────────────────┬─────────────────────────────┐
196 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
197 ├─────────────────────────────┼─────────────────────────────┤
198 │MT-Level │Safe │
199 └─────────────────────────────┴─────────────────────────────┘
200
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)
204SunOS 5.11 5 Jun 2007 td_sync_get_info(3C_DB)