share/man/man3lib/libc_db.3lib

   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
  47 calls certain routines that it expects the controlling process to provide.
  48 These process control  primitives allow \fBlibc_db\fR to:
  49 .RS +4
  50 .TP
  51 .ie t \(bu
  52 .el o
  53 Look up symbols in a target process.
  54 .RE
  55 .RS +4
  56 .TP
  57 .ie t \(bu
  58 .el o
  59 Stop and continue individual lightweight processes ( LWPs) within a target
  60 process.
  61 .RE
  62 .RS +4
  63 .TP
  64 .ie t \(bu
  65 .el o
  66 Stop and continue an entire target process.
  67 .RE
  68 .RS +4
  69 .TP
  70 .ie t \(bu
  71 .el o
  72 Read and write memory and registers in a target process.
  73 .RE
  74 .sp
  75 .LP
  76 Initially, a controlling process obtains a handle for a target process. Through
  77 that handle it can then obtain handles for the component objects of the target
  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)