te
Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
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.
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.
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]
libc_db - threads debugging library

cc [ flag... ] file... -lc_db [ library... ]
#include <proc_service.h>
#include <thread_db.h>

The libc_db library provides support for monitoring and manipulating threads-related aspects of a multithreaded program. There are at least two processes involved, the controlling process and one or more target processes. The controlling process is the libc_db client, which links with libc_db and uses libc_db to inspect or modify threads-related aspects of one or more target processes. The target processes must be multithreaded processes that use libc. The controlling process might or might not be multithreaded itself.

The most commonly anticipated use for libc_db is that the controlling process will be a debugger for a multithreaded program, hence the "db" in libc_db.

The libc_db library is dependent on the internal implementation details of libc. It is a "friend" of libc in the C++ sense, which is precisely the "value added" by libc_db. It encapsulates the knowledge of libc internals that a debugger needs to manipulate the threads-related state of a target process.

To be able to inspect and manipulate target processes, libc_db makes use of certain process control primitives that must be provided by the process using libc_db. The imported interfaces are defined in proc_service(3PROC). In other words, the controlling process is linked with libc_db and calls routines in libc_db. In turn, libc_db calls certain routines that it expects the controlling process to provide. These process control primitives allow libc_db to:

Initially, a controlling process obtains a handle for a target process. Through that handle it can then obtain handles for the component objects of the target process, its threads, its synchronization objects, and its thread-specific-data keys.

When libc_db needs to return sets of handles to the controlling process, for example, when returning handles for all the threads in a target process, it uses an iterator function. An iterator function calls back a client-specified function once for each handle to be returned, passing one handle back on each call to the callback function. The calling function also passes another parameter to the iterator function, which the iterator function passes on to the callback function. This makes it easy to build a linked list of thread handles for a particular target process. The additional parameter is the head of the linked list, and the callback function simply inserts the current handle into the linked list.

Callback functions are expected to return an integer. Iteration terminates early if a callback function returns a non-zero value. Otherwise, iteration terminates when there are no more handles to pass back.

The shared object libc_db.so.1 provides the public interfaces defined below. See Intro(3) for additional information on shared object interfaces.

td_init td_log

td_sync_get_info td_sync_get_stats

td_sync_setstate td_sync_waiters

td_ta_clear_event td_ta_delete

td_ta_enable_stats td_ta_event_addr

td_ta_event_getmsg td_ta_get_nthreads

td_ta_get_ph td_ta_get_stats

td_ta_map_addr2sync td_ta_map_id2thr

td_ta_map_lwp2thr td_ta_new

td_ta_reset_stats td_ta_set_event

td_ta_setconcurrency td_ta_sync_iter

td_ta_sync_tracking_enable td_ta_thr_iter

td_ta_tsd_iter td_thr_clear_event

td_thr_dbresume td_thr_dbsuspend

td_thr_event_enable td_thr_event_getmsg

td_thr_get_info td_thr_getfpregs

td_thr_getgregs td_thr_getxregs

td_thr_getxregsize td_thr_lockowner

td_thr_set_event td_thr_setfpregs

td_thr_setgregs td_thr_setprio

td_thr_setsigpending td_thr_setxregs

td_thr_sigsetmask td_thr_sleepinfo

td_thr_tsd td_thr_validate

/lib/libc_db.so.1 /lib/64/libc_db.so.1 See attributes(5) for description of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

MT-Level Safe

Intro(3), td_ta_new(3C_DB), attributes(5), threads(5)