NAME | SYNOPSIS | DESCRIPTION | FUNCTIONS | FILES | ATTRIBUTES | SEE ALSO
cc [ flag ... ] file ... -lthread_db [ library ... ] #include <proc_service.h> #include <thread_db.h>void td_event_addset(td_thr_events_t *, td_thr_events_e n);
The libthread_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 libthread_db client, which links with libthread_db and uses libthread_db to inspect or modify threads-related aspects of one or more target processes. The target processes must be multithreaded processes that use libthread or libpthread. The controlling process may or may not be multithreaded itself.
The most commonly anticipated use for libthread_db is that the controlling process will be a debugger for a multithreaded program, hence the "db" in libthread_db.
libthread_db is dependent on the internal implementation details of libthread. It is a "friend" of libthread in the C++ sense, which is precisely the "value added" by libthread_db. It encapsulates the knowledge of libthread internals that a debugger needs in order to manipulate the threads-related state of a target process.
To be able to inspect and manipulate target processes, libthread_db makes use of certain process control primitives that must be provided by the process using libthread_db. The imported interfaces are defined in proc_service(3PROC). In other words, the controlling process is linked with libthread_db, and it calls routines in libthread_db. libthread_db in turn calls certain routines that it expects the controlling process to provide. These process control primitives allow libthread_db to:
Look up symbols in a target process.
Stop and continue individual lightweight processes ( LWPs) within a target process.
Stop and continue an entire target process.
Read and write memory and registers in a target process.
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 libthread_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.
libthread_db relies on an "agent thread" in the target process for some of its operations. The "agent thread" is a system thread started when libthread_db attaches to a process through td_ta_new(3THR). In the current implementation, a brief window exists after the agent thread has been started, but before it has completed its initialization, in which libthread_db routines that require the agent thread will fail, returning a TD_NOCAPAB error status. This is particularly troublesome if the target process was stopped when td_ta_new() was called, so that the agent thread cannot be initialized. To avoid this problem, the target process must be allowed to make some forward progress after td_ta_new() is called. This limitation will be removed in a future release.
Description
Macro that adds a specific event type to an event set.
Macro that deletes a specific event type from an event set.
Macro that sets argument to NULL event set.
Macro that sets argument to set of all events.
Macro that tests whether an event set is the NULL set.
Macro that tests whether a specific event type is a member of an event set.
Performs initialization for interfaces.
Placeholder for future logging functionality.
Gets information for the synchronization object.
Gets statistics for the synchronization object.
Sets the state of the synchronization object.
Iteration function used for return of synchronization object handles.
Clears a set of event types in the process event mask.
Deregisters target process and deallocates internal process handle.
Turns statistics gathering on or off for the target process.
Returns event reporting address.
Returns process event message.
Gets the total number of threads in a process. .
Returns corresponding external process handle.
Gets statistics gathered for the target process.
Gets a synchronization object handles from a synchronization object's address.
Returns a thread handle for the given thread id.
Returns a thread handle for the given LWP id.
Registers target process and allocates internal process handle.
Resets all counters for statistics gathering for the target process.
Sets concurrency level for target process.
Sets a set of event types in the process event mask.
Returns handles of synchronization objects associated with a process.
Enables or disables synchronization object tracking.
Returns handles for threads that are part of the target process.
Returns the thread-specific data keys in use by the current process.
Clears a set of event types in the threads event mask.
Resumes thread.
Suspends thread.
Enables or disables event reporting.
Returns a process event message.
Gets thread information and updates
Gets the floating point registers for the given thread.
Gets the general registers for a given thread.
Gets the extra registers for the given thread.
Gets the size of the extra register set for the given thread.
Iterates over the set of locks owned by a thread. struct.
Sets a set of event types in the threads event mask.
Sets the floating point registers for the given thread. ti_sigmask
Sets the general registers for a given thread.
Sets the priority of a thread.
Changes a thread's pending signal state.
Sets the extra registers for the given thread.
Sets the signal mask of the thread.
Returns the synchronization handle for the object on which a thread is blocked.
Gets a thread's thread-specific data.
Tests a thread handle for validity.
See attributes(5) for description of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
MT Level | Safe |
libthread(3LIB), libthread_db(3LIB), proc_service(3PROC), rtld_db(3EXT), td_event_addset(3THR), td_event_delset(3THR), td_event_emptyset(3THR), td_event_fillset(3THR), td_eventisempty(3THR), td_eventismember(3THR), td_init(3THR), td_log(3THR), td_sync_get_info(3THR), td_sync_get_stats(3THR), td_sync_waiters(3THR), td_ta_delete(3THR), td_ta_enable_stats(3THR), td_ta_event_addr(3THR), td_ta_event_getmsg(3THR), td_ta_get_nthreads(3THR), td_ta_get_ph(3THR), td_ta_get_stats(3THR), td_ta_map_addr2sync(3THR), td_ta_map_id2thr(3THR), td_ta_map_lwp2thr(3THR), td_ta_new(3THR), td_ta_reset_stats(3THR), td_ta_set_event(3THR), td_ta_setconcurrency(3THR), td_ta_sync_iter(3THR), td_ta_sync_iter(3THR), td_ta_sync_tracking_enable(3THR), td_ta_tsd_iter(3THR), td_thr_clear_event(3THR), td_thr_dbresume(3THR), td_thr_dbsuspend(3THR), td_thr_event_enable(3THR), td_thr_event_getmsg(3THR), td_thr_get_info(3THR), td_thr_getfpregs(3THR), td_thr_getxregs(3THR), td_thr_getxregsize(3THR), td_thr_lockowner(3THR), td_thr_set_event(3THR), td_thr_setfpregs(3THR), td_thr_setgregs(3THR), td_thr_setprio(3THR), td_thr_sigsetmask(3THR), td_thr_setsigpending(3THR), td_thr_setxregs(3THR), td_thr_sleepinfo(3THR), td_thr_tsd(3THR), td_thr_validate(3THR), thr_getspecific(3THR), threads(3THR), attributes(5)
NAME | SYNOPSIS | DESCRIPTION | FUNCTIONS | FILES | ATTRIBUTES | SEE ALSO