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