SunOS man pages : td_ta_set_event (3)
Threads Library Functions td_ta_event_addr(3THR)
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
libthread_db
SYNOPSIS
cc [ flag ... ] file ... -lthread_db [ library ... ]
#include <proc_service.h>
#include <thread_db.h>
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);
void td_eventisempty(td_thr_events_t*);
DESCRIPTION
SunOS 5.8 Last change: 19 Oct 1998 1
Threads Library Functions td_ta_event_addr(3THR)
These routines comprise the thread event facility for
libthread_db(3THR). This facility allows the controlling
process to be notified when certain thread-related events
occur in a target process and to retrieve information asso-
ciated 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 Mani-
pulation 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 by
way of libthread_db.
Several flags can control event reporting, both a per-thread
and per event basis. Event reporting may further be enabled
or 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 the
td_thr_events_e and td_event_msg_t types and a list of the
event types and the values reported with them. The thread
handle, 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.
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
SunOS 5.8 Last change: 19 Oct 1998 2
Threads Library Functions td_ta_event_addr(3THR)
The thread became ready to execute.
TD_SLEEP
The thread has blocked on a synchronization 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 priority from
another thread.
TD_REAP
A thread is being reaped.
TD_CONCURRENCY
The number of LWPs is changing.
TD_TIMEOUT
A condition-variable timed wait expired.
td_ta_event_addr() 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.
td_thr_event_enable() 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 enabled if
SunOS 5.8 Last change: 19 Oct 1998 3
Threads Library Functions td_ta_event_addr(3THR)
on_off is non-zero; otherwise, it is disabled. To find out
whether or not event reporting is enabled on a thread, call
td_thr_getinfo() for the thread and examine the ti_traceme
field of the td_thrinfo_t structure it returns.
td_thr_set_event() and td_thr_clear_event() set and clear,
respectively, a set of event types in the event mask associ-
ated with the thread th_p. To inspect a thread's event mask,
call td_thr_getinfo() for the thread, and examine the
ti_events field of the td_thrinfo_t structure it returns.
td_ta_set_event() and td_ta_clear_event() are just like
td_thr_set_event () and td_thr_clear_event(), respectively,
except that the target process's global event mask is modi-
fied. There is no provision for inspecting the value of a
target process's global event mask.
td_thr_event_getmsg() returns in *msg the event message
associated with thread *th_p Reading a thread's event mes-
sage 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.
td_ta_event_getmsg() is just like 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 mes-
sage buffered, and it 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 will
return an event message from some such thread.
Event Set Manipulation Macros
Several macros are provided for manipulating event sets of
type 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.
SunOS 5.8 Last change: 19 Oct 1998 4
Threads Library Functions td_ta_event_addr(3THR)
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 in.
TD_BADPH
There is a NULL external process handle associated
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().
TD_ERR
Some other parameter error occurred, or a
libthread_db() internal error occurred.
The following value may be returned for
td_thr_event_enable(), td_thr_set_event(), and
td_thr_clear_event() only:
TD_NOCAPAB
The agent thread in the target process has not com-
pleted initialization, so this operation cannot be
performed. The operation can be performed after the
target process has been allowed to make some forward
progress. See also libthread_db(3THR).
ATTRIBUTES
See attributes(5) for description of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| MT-Level | Safe |
|_____________________________|_____________________________|
SunOS 5.8 Last change: 19 Oct 1998 5
Threads Library Functions td_ta_event_addr(3THR)
SEE ALSO
libthread_db(3THR), libthread_db(3LIB), attributes(5)
SunOS 5.8 Last change: 19 Oct 1998 6
|
 |
|
|
