| blob | 0eeac0e1cdfd8b1ef4cd532b2ca15091c52a248a |
1 '\" te
2 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH TD_SYNC_GET_INFO 3C_DB "Jun 5, 2007"
7 .SH NAME
8 td_sync_get_info, td_ta_sync_tracking_enable, td_sync_get_stats,
9 td_sync_setstate, td_sync_waiters \- operations on a synchronization object in
10 libc_db
11 .SH SYNOPSIS
12 .LP
13 .nf
14 cc [ \fIflag\fR... ] \fIfile\fR... -lc_db [ \fIlibrary\fR... ]
15 #include <proc_service.h>
16 #include <thread_db.h>
18 \fBtd_err_e\fR \fBtd_sync_get_info\fR(\fBconst td_synchandle_t *\fR\fIsh_p\fR, \fBtd_syncinfo_t *\fR\fIsi_p\fR);
19 .fi
21 .LP
22 .nf
23 \fBtd_err_e\fR \fBtd_ta_sync_tracking_enable\fR(\fBconst td_thragent_t *\fR\fIta_p\fR, \fBint\fR \fIon_off\fR);
24 .fi
26 .LP
27 .nf
28 \fBtd_err_e\fR \fBtd_sync_get_stats\fR(\fBconst td_synchandle_t *\fR\fIsh_p\fR, \fBtd_syncstats_t *\fR\fIss_p\fR);
29 .fi
31 .LP
32 .nf
33 \fBtd_err_e\fR \fBtd_sync_setstate\fR(\fBconst td_synchandle_t *\fR\fIsh_p\fR);
34 .fi
36 .LP
37 .nf
38 \fBtypedef int\fR \fBtd_thr_iter_f\fR(\fBconst td_thrhandle_t *\fR\fIth_p\fR, \fBvoid *\fR\fIcb_data_p\fR);
39 .fi
41 .LP
42 .nf
43 \fBtd_err_e\fR \fBtd_sync_waiters\fR(\fBconst td_synchandle_t *\fR\fIsh_p\fR, \fBtd_thr_iter_f *\fR\fIcb\fR,
44 \fBvoid *\fR\fIcb_data_p\fR);
45 .fi
47 .SH DESCRIPTION
48 .sp
49 .LP
50 Synchronization objects include mutexes, condition variables, semaphores, and
51 reader-writer locks. In the same way that thread operations use a thread handle
52 of type \fBtd_thrhandle_t\fR, operations on synchronization objects use a
53 synchronization object handle of type \fBtd_synchandle_t\fR.
54 .sp
55 .LP
56 The controlling process obtains synchronization object handles either by
57 calling the function \fBtd_ta_sync_iter()\fR to obtain handles for all
58 synchronization objects of the target process that are known to the
59 \fBlibc_db\fR library of interfaces, or by mapping the address of a
60 synchronization object in the address space of the target process to a handle
61 by calling \fBtd_ta_map_addr2sync\fR(3C_DB).
62 .sp
63 .LP
64 Not all synchronization objects that a process uses can be known to the
65 \fBlibc_db\fR library and returned by \fBtd_ta_sync_iter\fR(3C_DB). A
66 synchronization object is known to \fBlibc_db\fR only if it has been the target
67 of a synchronization primitive in the process (such as \fBmutex_lock()\fR,
68 described on the \fBmutex_init\fR(3C) manual page) after \fBtd_ta_new\fR(3C_DB)
69 has been called to attach to the process and \fBtd_ta_sync_tracking_enable()\fR
70 has been called to enable synchronization object tracking.
71 .sp
72 .LP
73 The \fBtd_ta_sync_tracking_enable()\fR function turns synchronization object
74 tracking on or off for the process identified by \fIta_p\fR, depending on
75 whether \fIon_off\fR is 0 (off) or non-zero (on).
76 .sp
77 .LP
78 The \fBtd_sync_get_info()\fR function fills in the \fBtd_syncinfo_t\fR
79 structure \fB*\fR\fIsi_p\fR with values for the synchronization object
80 identified by \fBsh_p\fR. The \fBtd_syncinfo_t\fR structure contains the
81 following fields:
82 .sp
83 .ne 2
84 .na
85 \fB\fBtd_thragent_t *\fR\fIsi_ta_p\fR\fR
86 .ad
87 .RS 29n
88 The internal process handle identifying the target process through which this
89 synchronization object handle was obtained. Synchronization objects may be
90 process-private or process-shared. In the latter case, the same synchronization
91 object may have multiple handles, one for each target process's "view" of the
92 synchronization object.
93 .RE
95 .sp
96 .ne 2
97 .na
98 \fB\fBpsaddr_t\fR \fIsi_sv_addr\fR\fR
99 .ad
100 .RS 29n
101 The address of the synchronization object in this target process's address
102 space.
103 .RE
105 .sp
106 .ne 2
107 .na
108 \fB\fBtd_sync_type_e\fR \fIsi_type\fR\fR
109 .ad
110 .RS 29n
111 The type of the synchronization variable: mutex, condition variable, semaphore,
112 or readers-writer lock.
113 .RE
115 .sp
116 .ne 2
117 .na
118 \fB\fBint\fR \fIsi_shared_type\fR\fR
119 .ad
120 .RS 29n
121 If \fIsi_shared_type\fR is non-zero, this synchronization object is
122 process-shared, otherwise it is process-private.
123 .RE
125 .sp
126 .ne 2
127 .na
128 \fB\fBtd_sync_flags_t\fR \fIsi_flags\fR\fR
129 .ad
130 .RS 29n
131 Flags dependent on the type of the synchronization object.
132 .RE
134 .sp
135 .ne 2
136 .na
137 \fB\fBint\fR \fIsi_state.sema_count\fR\fR
138 .ad
139 .RS 29n
140 Semaphores only. The current value of the semaphore
141 .RE
143 .sp
144 .ne 2
145 .na
146 \fB\fBint\fR \fIsi_state.nreaders\fR\fR
147 .ad
148 .RS 29n
149 Readers-writer locks only. The number of readers currently holding the lock, or
150 \fB-1\fR, if a writer is currently holding the lock.
151 .RE
153 .sp
154 .ne 2
155 .na
156 \fB\fBint\fR \fIsi_state.mutex_locked\fR\fR
157 .ad
158 .RS 29n
159 For mutexes only. Non-zero if and only if the mutex is currently locked.
160 .RE
162 .sp
163 .ne 2
164 .na
165 \fB\fBint\fR \fIsi_size\fR\fR
166 .ad
167 .RS 29n
168 The size of the synchronization object.
169 .RE
171 .sp
172 .ne 2
173 .na
174 \fB\fBuint8_t\fR \fIsi_has_waiters\fR\fR
175 .ad
176 .RS 29n
177 Non-zero if and only if at least one thread is blocked on this synchronization
178 object.
179 .RE
181 .sp
182 .ne 2
183 .na
184 \fB\fBuint8_t\fR \fIsi_is_wlocked\fR\fR
185 .ad
186 .RS 29n
187 For reader-writer locks only. The value is non-zero if and only if this lock is
188 held by a writer.
189 .RE
191 .sp
192 .ne 2
193 .na
194 \fB\fBuint8_t\fR \fIsi_rcount\fR\fR
195 .ad
196 .RS 29n
197 \fBPTHREAD_MUTEX_RECURSIVE\fR mutexes only. If the mutex is held, the recursion
198 count.
199 .RE
201 .sp
202 .ne 2
203 .na
204 \fB\fBuint8_t\fR \fIsi_prioceiling\fR\fR
205 .ad
206 .RS 29n
207 \fBPTHREAD_PRIO_PROTECT\fR protocol mutexes only. The priority ceiling.
208 .RE
210 .sp
211 .ne 2
212 .na
213 \fB\fBtd_thrhandle_t\fR \fIsi_owner\fR\fR
214 .ad
215 .RS 29n
216 Mutexes and readers-writer locks only. This is the thread holding the mutex, or
217 the write lock, if this is a reader-writer lock. The value is \fINULL\fR if
218 no one holds the mutex or write-lock.
219 .RE
221 .sp
222 .ne 2
223 .na
224 \fB\fBpid_t\fR \fIsi_ownerpid\fR\fR
225 .ad
226 .RS 29n
227 Mutexes only. For a locked process-shared mutex, this is the process-ID of the
228 process containing the owning thread.
229 .RE
231 .sp
232 .LP
233 The \fBtd_sync_get_stats()\fR function fills in the \fBtd_syncstats_t\fR
234 structure *\fIss_p\fR with values for the synchronization object identified by
235 \fIsh_p\fR. The \fBtd_syncstats_t\fR structure contains an embedded
236 \fBtd_syncinfo_t\fR structure that is filled in as described above for
237 \fBtd_sync_get_info()\fR. In addition, usage statistics gathered since
238 \fBtd_ta_sync_tracking_enable()\fR was called to enable synchronization object
239 tracking are returned in the \fBss_un.mutex\fR, \fBss_un.cond\fR,
240 \fBss_un.rwlock\fR, or \fBss_un.sema\fR members of the \fBtd_syncstats_t\fR
241 structure, depending on the type of the synchronization object.
242 .sp
243 .LP
244 The \fBtd_sync_setstate\fR function modifies the state of synchronization
245 object \fIsi_p\fR, depending on the synchronization object type. For mutexes,
246 \fBtd_sync_setstate\fR is unlocked if the value is \fB0\fR. Otherwise it is
247 locked. For semaphores, the semaphore's count is set to the value. For
248 reader-writer locks, the reader count set to the value if value is \fB>0\fR.
249 The count is set to write-locked if value is \fB-1\fR\&. It is set to unlocked
250 if the value is \fB0\fR. Setting the state of a synchronization object from a
251 \fBlibc_db\fR interface may cause the synchronization object's semantics to be
252 violated from the point of view of the threads in the target process. For
253 example, if a thread holds a mutex, and \fBtd_sync_setstate\fR is used to set
254 the mutex to unlocked, then a different thread will also be able to
255 subsequently acquire the same mutex.
256 .sp
257 .LP
258 The \fBtd_sync_waiters\fR function iterates over the set of thread handles of
259 threads blocked on \fIsh_p\fR. The callback function \fIcb\fR is called once
260 for each such thread handle, and is passed the thread handle and
261 \fIcb_data_p\fR. If the callback function returns a non-zero value, iteration
262 is terminated early. See \fBtd_ta_thr_iter\fR(3C_DB).
263 .SH RETURN VALUES
264 .sp
265 .ne 2
266 .na
267 \fB\fBTD_OK\fR \fR
268 .ad
269 .RS 13n
270 The call returned successfully.
271 .RE
273 .sp
274 .ne 2
275 .na
276 \fB\fBTD_BADTH\fR \fR
277 .ad
278 .RS 13n
279 An invalid thread handle was passed in.
280 .RE
282 .sp
283 .ne 2
284 .na
285 \fB\fBTD_DBERR\fR \fR
286 .ad
287 .RS 13n
288 A call to one of the imported interface routines failed.
289 .RE
291 .sp
292 .ne 2
293 .na
294 \fB\fBTD_ERR\fR \fR
295 .ad
296 .RS 13n
297 A libc_db-internal error occurred.
298 .RE
300 .SH ATTRIBUTES
301 .sp
302 .LP
303 See \fBattributes\fR(5) for descriptions of the following attributes:
304 .sp
306 .sp
307 .TS
308 box;
309 c | c
310 l | l .
311 ATTRIBUTE TYPE ATTRIBUTE VALUE
312 _
313 MT-Level Safe
314 .TE
316 .SH SEE ALSO
317 .sp
318 .LP
319 \fBlibc_db\fR(3LIB), \fBmutex_init\fR(3C), \fBtd_ta_map_addr2sync\fR(3C_DB),
320 \fBtd_ta_sync_iter\fR(3C_DB), \fBtd_ta_thr_iter\fR(3C_DB), \fBattributes\fR(5)