Threads Debugging Library Functions td_ta_event_addr(3C_DB)
NAME
td_ta_event_addr, td_thr_event_enable, td_ta_set_event,
td_thr_set_event, td_ta_clear_event, td_thr_clear_event,
td_ta_event_getmsg, td_thr_event_getmsg, td_event_emptyset,
td_event_fillset, td_event_addset, td_event_delset,
td_eventismember, td_eventisempty - thread events in libc_db
SYNOPSIS
cc [ flag... ] file... -lc_db [ library... ]
#include
#include
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_thr_event_enable(const td_thrhandle_t *th_p, int on_off);
td_err_e td_thr_set_event(const td_thrhandle_t *th_p, td_thr_events_t *events);
td_err_e td_ta_set_event(const td_thragent_t *ta_p, td_thr_events_t *events);
td_err_e td_thr_clear_event(const td_thrhandle_t *th_p, td_thr_events_t *events);
td_err_e td_ta_clear_event(const td_thragent_t *ta_p, td_thr_events_t *events);
td_err_e td_thr_event_getmsg(const td_thrhandle_t *th_p, td_event_msg_t *msg);
td_err_e td_ta_event_getmsg(const td_thragent_t *ta_p, td_event_msg_t *msg);
void td_event_emptyset(td_thr_events_t *);
void td_event_fillset(td_thr_events_t *);
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_eventismember(td_thr_events_t *, td_thr_events_e n);
SunOS 5.11 Last change: 19 Oct 1998 1
Threads Debugging Library Functions td_ta_event_addr(3C_DB)
void td_eventisempty(td_thr_events_t*);
DESCRIPTION
These functions comprise the thread event facility forlibc_db(3LIB). This facility allows the controlling process
to be notified when certain thread-related events occur in a
target process and to retrieve information associated with these events. An event consists of an event type, and optionally, some associated event data, depending on the event type. See the section titled "Event Set Manipulation Macros" that follows.The event type and the associated event data, if any, con-
stitute an "event message." "Reporting an event" means delivering an event message to the controlling process byway of libc_db.
Several flags can control event reporting, both a per-thread
and per event basis. Event reporting may further be enabledor disabled for a thread. There is not only a per-thread
event mask that specifies which event types should be reported for that thread, but there is also a global event mask that applies to all threads. An event is reported, if and only if, the executing thread has event reporting enabled, and either the event type is enabled in the executing thread's event mask, or the event type is enabled in the global event mask. Each thread has associated with it an event buffer in which it stores the most recent event message it has generated, the type of the most recent event that it reported, and, depending on the event type, some additional information related to that event. See the section titled "Event Set Manipulation Macros" for a description of thetd_thr_events_e and td_event_msg_t types and a list of the
event types and the values reported with them. The threadhandle, type td_thrhandle_t, the event type, and the possi-
ble value, together constitute an event message. Each thread's event buffer holds at most one event message. Each event type has an event reporting address associated with it. A thread reports an event by writing the event message into the thread's event buffer and having control reach the event reporting address for that event type.SunOS 5.11 Last change: 19 Oct 1998 2
Threads Debugging Library Functions td_ta_event_addr(3C_DB)
Typically, the controlling process sets a breakpoint at the event reporting address for one or more event types. When the breakpoint is hit, the controlling process knows that an event of the corresponding type has occurred. The event types, and the additional information, if any, reported with each event, are:TD_READY The thread became ready to execute.
TD_SLEEP The thread has blocked on a synchroniza-
tion object.TD_SWITCHTO A runnable thread is being assigned to
LWP.TD_SWITCHFROM A running thread is being removed from its
LWP.TD_LOCK_TRY A thread is trying to get an unavailable
lock.TD_CATCHSIG A signal was posted to a thread.
TD_IDLE An LWP is becoming idle.
TD_CREATE A thread is being created.
TD_DEATH A thread has terminated.
TD_PREEMPT A thread is being preempted.
TD_PRI_INHERIT A thread is inheriting an elevated prior-
ity from another thread.TD_REAP A thread is being reaped.
TD_CONCURRENCY The number of LWPs is changing.
SunOS 5.11 Last change: 19 Oct 1998 3
Threads Debugging Library Functions td_ta_event_addr(3C_DB)
TD_TIMEOUT A condition-variable timed wait expired.
The td_ta_event_addr() function returns in *notify_p the
event reporting address associated with event type event. The controlling process may then set a breakpoint at that address. If a thread hits that breakpoint, it reports an event of type event.The td_thr_event_enable() function enables or disables event
reporting for thread th_p. If a thread has event reporting
disabled, it will not report any events. Threads are started with event reporting disabled. Event reporting is enabledif on_off is non-zero; otherwise, it is disabled. To deter-
mine whether or not event reporting is enabled on a thread,call td_thr_getinfo() for the thread and examine the
ti_traceme member of the td_thrinfo_t structure it returns.
The td_thr_set_event() and td_thr_clear_event() functions
set and clear, respectively, a set of event types in theevent mask associated with the thread th_p. To inspect a
thread's event mask, call td_thr_getinfo() for the thread
and examine the ti_events member of the td_thrinfo_t struc-
ture it returns.The td_ta_set_event() and td_ta_clear_event() functions
identical to td_thr_set_event() and td_thr_clear_event(),
respectively, except that the target process's global event mask is modified. There is no provision for inspecting the value of a target process's global event mask.The td_thr_event_getmsg() function returns in *msg the event
message associated with thread *th_p. Reading a thread's
event message consumes the message, emptying the thread's event buffer. As noted above, each thread's event buffer holds at most one event message; if a thread reports a second event before the first event message has been read, the second event message overwrites the first.The td_ta_event_getmsg() function is identical to
td_thr_event_getmsg(), except that it is passed a process
handle rather than a thread handle. It selects some thread that has an event message buffered and returns that thread's message. The thread selected is undefined, except that as long as at least one thread has an event message buffered, it returns an event message from some such thread.SunOS 5.11 Last change: 19 Oct 1998 4
Threads Debugging Library Functions td_ta_event_addr(3C_DB)
Event Set Manipulation Macros Several macros are provided for manipulating event sets oftype td_thr_events_t:
td_event_emptyset Sets its argument to the NULL event
set.td_event_fillset Sets its argument to the set of all
events.td_event_addset Adds a specific event type to an event
set.td_event_delset Deletes a specific event type from an
event set.td_eventismember Tests whether a specific event type is
a member of an event set.td_eventisempty Tests whether an event set is the NULL
set.RETURN VALUES
The following values may be returned for all thread event routines:TD_OK The call returned successfully.
TD_BADTH An invalid thread handle was passed in.
TD_BADTA An invalid internal process handle was passed.
TD_BADPH There is a NULL external process handle associ-
ated with this internal process handle.TD_DBERR A call to one of the imported interface routines
failed.TD_NOMSG No event message was available to return to
td_thr_event_getmsg() or td_ta_event_getmsg().
SunOS 5.11 Last change: 19 Oct 1998 5
Threads Debugging Library Functions td_ta_event_addr(3C_DB)
TD_ERR Some other parameter error occurred, or a
libc_db() internal error occurred.
The following value can be returned fortd_thr_event_enable(), td_thr_set_event(), and
td_thr_clear_event() only:
TD_NOCAPAB Because the agent thread in the target pro-
cess has not completed initialization, this operation cannot be performed. The operation can be performed after the target process has been allowed to make some forward progress.See libc_db(3LIB).
ATTRIBUTES
See attributes(5) for description of the following attri-
butes:____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| MT-Level | Safe |
|_____________________________|_____________________________|
SEE ALSO
libc_db(3LIB), attributes(5)
SunOS 5.11 Last change: 19 Oct 1998 6