1 '\" te
2 .\" Copyright (c) 2004, 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 LIBC_DB 3LIB "Mar 24, 2004"
7 .SH NAME
8 libc_db \- threads debugging library
9 .SH SYNOPSIS
10 .LP
11 .nf
12 cc [ \fIflag\fR ... ] \fIfile\fR ... \fB-lc_db\fR [ \fIlibrary \fR... ]
13 #include <\fBproc_service.h\fR>
14 #include <\fBthread_db.h\fR>
15 .fi
16
17 .SH DESCRIPTION
18 .sp
19 .LP
20 The \fBlibc_db\fR library provides support for monitoring and manipulating
21 threads-related aspects of a multithreaded program. There are at least two
22 processes involved, the controlling process and one or more target processes.
23 The controlling process is the \fBlibc_db\fR client, which links with
24 \fBlibc_db\fR and uses \fBlibc_db\fR to inspect or modify threads-related
25 aspects of one or more target processes. The target processes must be
26 multithreaded processes that use \fBlibc\fR. The controlling process mignt or
27 might not be multithreaded itself.
28 .sp
29 .LP
30 The most commonly anticipated use for \fBlibc_db\fR is that the controlling
31 process will be a debugger for a multithreaded program, hence the "db" in
32 \fBlibc_db\fR.
33 .sp
34 .LP
35 The \fBlibc_db\fR library is dependent on the internal implementation details
36 of \fBlibc\fR. It is a "friend" of \fBlibc\fR in the C++ sense, which is
37 precisely the "value added" by \fBlibc_db\fR. It encapsulates the knowledge of
38 \fBlibc\fR internals that a debugger needs to manipulate the threads-related
39 state of a target process.
40 .sp
41 .LP
42 To be able to inspect and manipulate target processes, \fBlibc_db\fR makes use
43 of certain process control primitives that must be provided by the process
44 using \fBlibc_db\fR. The imported interfaces are defined in
45 \fBproc_service\fR(3PROC). In other words, the controlling process is linked
46 with \fBlibc_db\fR and calls routines in \fBlibc_db\fR. In turn, \fBlibc_db\fR
78 process, its threads, its synchronization objects, and its thread-specific-data
79 keys.
80 .sp
81 .LP
82 When \fBlibc_db\fR needs to return sets of handles to the controlling process,
83 for example, when returning handles for all the threads in a target process, it
84 uses an iterator function. An iterator function calls back a client-specified
85 function once for each handle to be returned, passing one handle back on each
86 call to the callback function. The calling function also passes another
87 parameter to the iterator function, which the iterator function passes on to
88 the callback function. This makes it easy to build a linked list of thread
89 handles for a particular target process. The additional parameter is the head
90 of the linked list, and the callback function simply inserts the current handle
91 into the linked list.
92 .sp
93 .LP
94 Callback functions are expected to return an integer. Iteration terminates
95 early if a callback function returns a non-zero value. Otherwise, iteration
96 terminates when there are no more handles to pass back.
97 .SH INTERFACES
98 .sp
99 .LP
100 The shared object \fBlibc_db.so.1\fR provides the public interfaces defined
101 below. See \fBIntro\fR(3) for additional information on shared object
102 interfaces.
103 .sp
104
105 .sp
106 .TS
107 l l
108 l l .
109 \fBtd_init\fR \fBtd_log\fR
110 \fBtd_sync_get_info\fR \fBtd_sync_get_stats\fR
111 \fBtd_sync_setstate\fR \fBtd_sync_waiters\fR
112 \fBtd_ta_clear_event\fR \fBtd_ta_delete\fR
113 \fBtd_ta_enable_stats\fR \fBtd_ta_event_addr\fR
114 \fBtd_ta_event_getmsg\fR \fBtd_ta_get_nthreads\fR
115 \fBtd_ta_get_ph\fR \fBtd_ta_get_stats\fR
116 \fBtd_ta_map_addr2sync\fR \fBtd_ta_map_id2thr\fR
117 \fBtd_ta_map_lwp2thr\fR \fBtd_ta_new\fR
118 \fBtd_ta_reset_stats\fR \fBtd_ta_set_event\fR
119 \fBtd_ta_setconcurrency\fR \fBtd_ta_sync_iter\fR
120 \fBtd_ta_sync_tracking_enable\fR \fBtd_ta_thr_iter\fR
121 \fBtd_ta_tsd_iter\fR \fBtd_thr_clear_event\fR
122 \fBtd_thr_dbresume\fR \fBtd_thr_dbsuspend\fR
123 \fBtd_thr_event_enable\fR \fBtd_thr_event_getmsg\fR
124 \fBtd_thr_get_info\fR \fBtd_thr_getfpregs\fR
125 \fBtd_thr_getgregs\fR \fBtd_thr_getxregs\fR
126 \fBtd_thr_getxregsize\fR \fBtd_thr_lockowner\fR
127 \fBtd_thr_set_event\fR \fBtd_thr_setfpregs\fR
128 \fBtd_thr_setgregs\fR \fBtd_thr_setprio\fR
129 \fBtd_thr_setsigpending\fR \fBtd_thr_setxregs\fR
130 \fBtd_thr_sigsetmask\fR \fBtd_thr_sleepinfo\fR
131 \fBtd_thr_tsd\fR \fBtd_thr_validate\fR
132 .TE
133
134 .SH FILES
135 .sp
136 .ne 2
137 .na
138 \fB\fB/lib/libc_db.so.1\fR\fR
139 .ad
140 .RS 24n
141 shared object
142 .RE
143
144 .sp
145 .ne 2
146 .na
147 \fB\fB/lib/64/libc_db.so.1\fR\fR
148 .ad
149 .RS 24n
150 64-bit shared object
151 .RE
152
153 .SH ATTRIBUTES
154 .sp
155 .LP
156 See \fBattributes\fR(5) for description of the following attributes:
157 .sp
158
159 .sp
160 .TS
161 box;
162 c | c
163 l | l .
164 ATTRIBUTE TYPE ATTRIBUTE VALUE
165 MT-Level Safe
166 .TE
167
168 .SH SEE ALSO
169 .sp
170 .LP
171 \fBIntro\fR(3), \fBtd_ta_new\fR(3C_DB), \fBattributes\fR(5), \fBthreads\fR(5)
|
1 '\" te
2 .\" Copyright (c) 2004, 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 LIBC_DB 3LIB "Aug 19, 2019"
7 .SH NAME
8 libc_db \- threads debugging library
9 .SH SYNOPSIS
10 .nf
11 cc [ \fIflag\fR... ] \fIfile\fR... \fB-lc_db\fR [ \fIlibrary\fR... ]
12 #include <\fBproc_service.h\fR>
13 #include <\fBthread_db.h\fR>
14 .fi
15
16 .SH DESCRIPTION
17 The \fBlibc_db\fR library provides support for monitoring and manipulating
18 threads-related aspects of a multithreaded program. There are at least two
19 processes involved, the controlling process and one or more target processes.
20 The controlling process is the \fBlibc_db\fR client, which links with
21 \fBlibc_db\fR and uses \fBlibc_db\fR to inspect or modify threads-related
22 aspects of one or more target processes. The target processes must be
23 multithreaded processes that use \fBlibc\fR. The controlling process might or
24 might not be multithreaded itself.
25 .sp
26 .LP
27 The most commonly anticipated use for \fBlibc_db\fR is that the controlling
28 process will be a debugger for a multithreaded program, hence the "db" in
29 \fBlibc_db\fR.
30 .sp
31 .LP
32 The \fBlibc_db\fR library is dependent on the internal implementation details
33 of \fBlibc\fR. It is a "friend" of \fBlibc\fR in the C++ sense, which is
34 precisely the "value added" by \fBlibc_db\fR. It encapsulates the knowledge of
35 \fBlibc\fR internals that a debugger needs to manipulate the threads-related
36 state of a target process.
37 .sp
38 .LP
39 To be able to inspect and manipulate target processes, \fBlibc_db\fR makes use
40 of certain process control primitives that must be provided by the process
41 using \fBlibc_db\fR. The imported interfaces are defined in
42 \fBproc_service\fR(3PROC). In other words, the controlling process is linked
43 with \fBlibc_db\fR and calls routines in \fBlibc_db\fR. In turn, \fBlibc_db\fR
75 process, its threads, its synchronization objects, and its thread-specific-data
76 keys.
77 .sp
78 .LP
79 When \fBlibc_db\fR needs to return sets of handles to the controlling process,
80 for example, when returning handles for all the threads in a target process, it
81 uses an iterator function. An iterator function calls back a client-specified
82 function once for each handle to be returned, passing one handle back on each
83 call to the callback function. The calling function also passes another
84 parameter to the iterator function, which the iterator function passes on to
85 the callback function. This makes it easy to build a linked list of thread
86 handles for a particular target process. The additional parameter is the head
87 of the linked list, and the callback function simply inserts the current handle
88 into the linked list.
89 .sp
90 .LP
91 Callback functions are expected to return an integer. Iteration terminates
92 early if a callback function returns a non-zero value. Otherwise, iteration
93 terminates when there are no more handles to pass back.
94 .SH INTERFACES
95 The shared object \fBlibc_db.so.1\fR provides the public interfaces defined
96 below. See \fBIntro\fR(3) for additional information on shared object
97 interfaces.
98 .sp
99
100 .sp
101 .TS
102 l l
103 l l .
104 \fBtd_init\fR \fBtd_log\fR
105 \fBtd_sync_get_info\fR \fBtd_sync_get_stats\fR
106 \fBtd_sync_setstate\fR \fBtd_sync_waiters\fR
107 \fBtd_ta_clear_event\fR \fBtd_ta_delete\fR
108 \fBtd_ta_enable_stats\fR \fBtd_ta_event_addr\fR
109 \fBtd_ta_event_getmsg\fR \fBtd_ta_get_nthreads\fR
110 \fBtd_ta_get_ph\fR \fBtd_ta_get_stats\fR
111 \fBtd_ta_map_addr2sync\fR \fBtd_ta_map_id2thr\fR
112 \fBtd_ta_map_lwp2thr\fR \fBtd_ta_new\fR
113 \fBtd_ta_reset_stats\fR \fBtd_ta_set_event\fR
114 \fBtd_ta_setconcurrency\fR \fBtd_ta_sync_iter\fR
115 \fBtd_ta_sync_tracking_enable\fR \fBtd_ta_thr_iter\fR
116 \fBtd_ta_tsd_iter\fR \fBtd_thr_clear_event\fR
117 \fBtd_thr_dbresume\fR \fBtd_thr_dbsuspend\fR
118 \fBtd_thr_event_enable\fR \fBtd_thr_event_getmsg\fR
119 \fBtd_thr_get_info\fR \fBtd_thr_getfpregs\fR
120 \fBtd_thr_getgregs\fR \fBtd_thr_getxregs\fR
121 \fBtd_thr_getxregsize\fR \fBtd_thr_lockowner\fR
122 \fBtd_thr_set_event\fR \fBtd_thr_setfpregs\fR
123 \fBtd_thr_setgregs\fR \fBtd_thr_setprio\fR
124 \fBtd_thr_setsigpending\fR \fBtd_thr_setxregs\fR
125 \fBtd_thr_sigsetmask\fR \fBtd_thr_sleepinfo\fR
126 \fBtd_thr_tsd\fR \fBtd_thr_validate\fR
127 .TE
128
129 .SH FILES
130 .ne 2
131 .na
132 \fB/lib/libc_db.so.1\fR
133 .ad
134 .RS 24n
135 shared object
136 .RE
137
138 .sp
139 .ne 2
140 .na
141 \fB/lib/64/libc_db.so.1\fR
142 .ad
143 .RS 24n
144 64-bit shared object
145 .RE
146
147 .SH ATTRIBUTES
148 See \fBattributes\fR(5) for description of the following attributes:
149 .sp
150
151 .sp
152 .TS
153 box;
154 c | c
155 l | l .
156 ATTRIBUTE TYPE ATTRIBUTE VALUE
157 MT-Level Safe
158 .TE
159
160 .SH SEE ALSO
161 \fBIntro\fR(3), \fBtd_ta_new\fR(3C_DB), \fBattributes\fR(5), \fBthreads\fR(5)
|