SunOS man pages


	www.sun.com	docs.sun.com \| \| \|

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

Threads Library Functions

libthread_db(3THR)

DESCRIPTION
FUNCTIONS
FILES
ATTRIBUTES
SEE ALSO

NAME

libthread_db - library of interfaces for monitoring and manipulating threads-related aspects of multithreaded programs

SYNOPSIS

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);

void td_event_delset(td_thr_events_t *, td_thr_events_e n);

void td_event_emptyset(td_thr_events_t *);

void td_event_fillset(td_thr_events_t *);

void td_eventisempty(td_thr_events_t *);

void td_eventismember(td_thr_events_t *, td_thr_events_e n);

td_err_e td_init();

void td_log();

td_err_e td_sync_get_info(const td_synchandle_t *sh_p, td_syncstats_t *ss_p);

td_err_e td_sync_get_stats(const td_synchandle_t *sh_p, td_syncinfo_t *si_p);

td_err_e td_sync_setstate(const td_synchandle_t *sh_p, int value);

td_err_e td_sync_waiters(const td_synchandle_t *sh_p, td_thr_iter_f *cb, void *cb_data_p);

td_err_e td_thr_clear_event(const td_thrhandle_t *th_p, td_thr_events_t *events);

td_err_e td_ta_delete(td_thragent_t *ta_p);

td_err_e td ta_enable_stats(const td_thragent_t*ta_p, int on_off);

td_err_e td_ta_event_addr(const td_thragent_t*ta_p, u_long event, td_notify_t *notify_p);

td_err_e td_ta_event_getmsg(const td_thragent_t *ta_p, td_event_msg_t *msg);

td_err_e td_ta_get_nthreads(const td_thragent_t *ta_p, int *nthread_p);

td_err_e td_ta_get_ph(const td_thragent_t *ta_p, struct ps_prochandle **ph_pp);

td_err_e td_ta_get_stats(const td_thragent_t *ta_p, td_ta_stats_t *tstats);

td_err_e td_ta_map_addr2sync(const td_thragent_t *ta_p, psaddr_t addr td_synchandle_t *sh_p);

td_err_e td_ta_map_id2thr(const td_thragent_t *ta_p, thread_t tid, td_thrhandle_t *th_p);

td_err_e td_ta_map_lwp2thr(const td_thragent_t *ta_p, lwpid_t lwpid, td_thrhandle_t *th_p);

td_err_e td_ta_new(struct ps_prochandle *ph_p, td_thragent_t **ta_pp);

td_err_e td_ta_reset_stats(const td_thragent_t *ta_p);

td_err_e td_ta_setconcurrency(const td_thragent_t *ta_p, int level);

td_err_e td_ta_sync_iter(const td_thragent_t *ta_p, td_sync_iter_f *cb, void *cbdata_p);

td_err_e td_ta_sync_tracking_enable(const td_thragent_t *ta_p, int on_off);

td_err_e td_ta_thr_iter(const td_thragent_t *ta_p, td_key_iter_f *cb, void *cbdata_p);

td_err_e td_ta_tsd_iter(const td_thragent_t *ta_p, td_key_iter_f *cb, void *cbdata_p);

td_err_e td_thr_clear_event(const td_thrhandle_t *th_p, td_thr_events_t *events);

td_err_e td_thr_dbresume(const td_thrhandle_t *th_p);

td_err_e td_thr_dbsuspend(const td_thrhandle_t *th_p);

td_err_e td_thr_event_enable(const td_thrhandle_t *th_p, int on_off);

td_err_e td_thr_event_getmsg(const td_thrhandle_t, td_event_msg_t *msg);

td_err_e td_thr_get_info(const td_thrhandle_t *th_p, td_thrinfo_t *ti_p);

td_err_e td_thr_getfpregs(const td_thrhandle_t *th_p, prfpregset_t *fpregset);

td_err_e td_thr_getgregs(const td_thrhandle_t *th_p, prgregset_t regset);

td_err_e td_thr_getxregs(const td_thrhandle_t *th_p, void *xregset);

td_err_e td_thr_getxregsize(const td_thrhandle_t *th_p, int *xregsize);

td_err_e td_thr_lockowner(const td_thrhandle_t *th_p, td_sync_iter_f *cb, void *cb_data_p);

td_err_e td_thr_set_event(const td_thrhandle_t *th_p, td_thr_events_t *events);

td_err_e td_thr_setfpregs(const td_thrhandle_t *th_p, prfpregset_t *fpregset);

td_err_e td_thr_setgregs(const td_thrhandle_t *th_p, const prgregset_t regset);

td_err_e td_thr_setprio(const td_thrhandle_t *th_p, const int new_prio);

td_err_e td_thr_setsigpending(const td_thrhandle_t *th_p, const uchar_t, ti_pending_flag, const sigset_t ti_pending);

td_err_e td_thr_setxregs(const td_thrhandle_t *th_p, const void *xregset);

td_err_e td_thr_sigsetmask(const td_thrhandle_t *th_p, const sigset_t ti_sigmask);

td_err_e td_thr_sleepinfo(const td_thrhandle_t *th_p, td_synchandle_t *sh_p);

td_err_e td_thr_tsd(const td_thrhandle_t *th_p, const thread_key_t key, void **data_pp);

td_err_e td_thr_validate(const td_thrhandle_t *th_p);

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.

FUNCTIONS

Name: Description
td_event_addset(): Macro that adds a specific event type to an event set.
td_event_delset(): Macro that deletes a specific event type from an event set.
td_event_emptyset(): Macro that sets argument to NULL event set.
td_event_fillset(): Macro that sets argument to set of all events.
td_eventisempty(): Macro that tests whether an event set is the NULL set.
td_eventismember(): Macro that tests whether a specific event type is a member of an event set.
td_init(): Performs initialization for interfaces.
td_log(): Placeholder for future logging functionality.
td_sync_get_info(): Gets information for the synchronization object.
td_sync_get_stats(): Gets statistics for the synchronization object.
td_sync_setstate(): Sets the state of the synchronization object.
td_sync_waiters(): Iteration function used for return of synchronization object handles.
td_ta_clear_event(): Clears a set of event types in the process event mask.
td_ta_delete(): Deregisters target process and deallocates internal process handle.
td_ta_enable_stats(): Turns statistics gathering on or off for the target process.
td_ta_event_addr(): Returns event reporting address.
td_ta_event_getmsg(): Returns process event message.
td_ta_get_nthreads(): Gets the total number of threads in a process. .
td_ta_get_ph(): Returns corresponding external process handle.
td_ta_get_stats(): Gets statistics gathered for the target process.
td_ta_map_addr2sync(): Gets a synchronization object handles from a synchronization object's address.
td_ta_map_id2thr(): Returns a thread handle for the given thread id.
td_ta_map_lwp2thr(): Returns a thread handle for the given LWP id.
td_ta_new(): Registers target process and allocates internal process handle.
td_ta_reset_stats(): Resets all counters for statistics gathering for the target process.
td_ta_setconcurrency(): Sets concurrency level for target process.
td_ta_set_event(): Sets a set of event types in the process event mask.
td_ta_sync_iter(): Returns handles of synchronization objects associated with a process.
td_ta_sync_tracking_enable(): Enables or disables synchronization object tracking.
td_ta_thr_iter(): Returns handles for threads that are part of the target process.
td_ta_tsd_iter(): Returns the thread-specific data keys in use by the current process.
td_thr_clear_event(): Clears a set of event types in the threads event mask.
td_thr_dbresume(): Resumes thread.
td_thr_dbsuspend(): Suspends thread.
td_thr_event_enable(): Enables or disables event reporting.
td_thr_event_getmsg(): Returns a process event message.
td_thr_get_info(): Gets thread information and updates
td_thr_getfpregs(): Gets the floating point registers for the given thread.
td_thr_getgregs(): Gets the general registers for a given thread.
td_thr_getxregs(): Gets the extra registers for the given thread.
td_thr_getxregsize(): Gets the size of the extra register set for the given thread.
td_thr_lockowner(): Iterates over the set of locks owned by a thread. struct.
td_thr_set_event(): Sets a set of event types in the threads event mask.
td_thr_setfpregs(): Sets the floating point registers for the given thread. ti_sigmask
td_thr_setgregs(): Sets the general registers for a given thread.
td_thr_setprio(): Sets the priority of a thread.
td_thr_setsigpending(): Changes a thread's pending signal state.
td_thr_setxregs(): Sets the extra registers for the given thread.
td_thr_sigsetmask(): Sets the signal mask of the thread.
td_thr_sleepinfo(): Returns the synchronization handle for the object on which a thread is blocked.
td_thr_tsd(): Gets a thread's thread-specific data.
td_thr_validate(): Tests a thread handle for validity.

FILES

lthread_db

ATTRIBUTES

See attributes(5) for description of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
MT Level	Safe

NAME

SYNOPSIS

DESCRIPTION

FUNCTIONS

FILES

ATTRIBUTES

SEE ALSO