libc_db

Synopsis

Description

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 mignt 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.

INTERFACES

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