1td_ta_event_addr(3C_DB)Threads Debugging Library Functiontsd_ta_event_addr(3C_DB)
2
6 td_ta_event_addr, td_thr_event_enable, td_ta_set_event,
7 td_thr_set_event, td_ta_clear_event, td_thr_clear_event,
8 td_ta_event_getmsg, td_thr_event_getmsg, td_event_emptyset,
9 td_event_fillset, td_event_addset, td_event_delset, td_eventismember,
10 td_eventisempty - thread events in libc_db
11
13 cc [ flag... ] file... -lc_db [ library... ]
14 #include <proc_service.h>
15 #include <thread_db.h>
16 td_err_e td_ta_event_addr(const td_thragent_t *ta_p, u_long event,td_notify_t *notify_p);
18 td_err_e td_thr_event_enable(const td_thrhandle_t *th_p, int on_off);
21 td_err_e td_thr_set_event(const td_thrhandle_t *th_p, td_thr_events_t *events);
24 td_err_e td_ta_set_event(const td_thragent_t *ta_p, td_thr_events_t *events);
27 td_err_e td_thr_clear_event(const td_thrhandle_t *th_p, td_thr_events_t *events);
30 td_err_e td_ta_clear_event(const td_thragent_t *ta_p, td_thr_events_t *events);
33 td_err_e td_thr_event_getmsg(const td_thrhandle_t *th_p, td_event_msg_t *msg);
36 td_err_e td_ta_event_getmsg(const td_thragent_t *ta_p, td_event_msg_t *msg);
39 void td_event_emptyset(td_thr_events_t *);
42 void td_event_fillset(td_thr_events_t *);
45 void td_event_addset(td_thr_events_t *, td_thr_events_e n);
48 void td_event_delset(td_thr_events_t *, td_thr_events_e n);
51 void td_eventismember(td_thr_events_t *, td_thr_events_e n);
54 void td_eventisempty(td_thr_events_t*);
57
60 These functions comprise the thread event facility for libc_db(3LIB).
61 This facility allows the controlling process to be notified when cer‐
62 tain thread-related events occur in a target process and to retrieve
63 information associated with these events. An event consists of an
64 event type, and optionally, some associated event data, depending on
65 the event type. See the section titled "Event Set Manipulation Macros"
66 that follows.
67 The event type and the associated event data, if any, constitute an
70 "event message." "Reporting an event" means delivering an event mes‐
71 sage to the controlling process by way of libc_db.
72 Several flags can control event reporting, both a per-thread and per
75 event basis. Event reporting may further be enabled or disabled for a
76 thread. There is not only a per-thread event mask that specifies which
77 event types should be reported for that thread, but there is also a
78 global event mask that applies to all threads.
79 An event is reported, if and only if, the executing thread has event
82 reporting enabled, and either the event type is enabled in the execut‐
83 ing thread's event mask, or the event type is enabled in the global
84 event mask.
85 Each thread has associated with it an event buffer in which it stores
88 the most recent event message it has generated, the type of the most
89 recent event that it reported, and, depending on the event type, some
90 additional information related to that event. See the section titled
91 "Event Set Manipulation Macros" for a description of the
92 td_thr_events_e and td_event_msg_t types and a list of the event types
93 and the values reported with them. The thread handle, type td_thrhan‐
94 dle_t, the event type, and the possible value, together constitute an
95 event message. Each thread's event buffer holds at most one event mes‐
96 sage.
97 Each event type has an event reporting address associated with it. A
100 thread reports an event by writing the event message into the thread's
101 event buffer and having control reach the event reporting address for
102 that event type.
103 Typically, the controlling process sets a breakpoint at the event
106 reporting address for one or more event types. When the breakpoint is
107 hit, the controlling process knows that an event of the corresponding
108 type has occurred.
109 The event types, and the additional information, if any, reported with
112 each event, are:
113 TD_READY The thread became ready to execute.
115 TD_SLEEP The thread has blocked on a synchronization object.
118 TD_SWITCHTO A runnable thread is being assigned to LWP.
121 TD_SWITCHFROM A running thread is being removed from its LWP.
124 TD_LOCK_TRY A thread is trying to get an unavailable lock.
127 TD_CATCHSIG A signal was posted to a thread.
130 TD_IDLE An LWP is becoming idle.
133 TD_CREATE A thread is being created.
136 TD_DEATH A thread has terminated.
139 TD_PREEMPT A thread is being preempted.
142 TD_PRI_INHERIT A thread is inheriting an elevated priority from
145 another thread.
146 TD_REAP A thread is being reaped.
149 TD_CONCURRENCY The number of LWPs is changing.
152 TD_TIMEOUT A condition-variable timed wait expired.
155 The td_ta_event_addr() function returns in *notify_p the event report‐
159 ing address associated with event type event. The controlling process
160 may then set a breakpoint at that address. If a thread hits that
161 breakpoint, it reports an event of type event.
162 The td_thr_event_enable() function enables or disables event reporting
165 for thread th_p. If a thread has event reporting disabled, it will not
166 report any events. Threads are started with event reporting disabled.
167 Event reporting is enabled if on_off is non-zero; otherwise, it is
168 disabled. To determine whether or not event reporting is enabled on a
169 thread, call td_thr_getinfo() for the thread and examine the ti_traceme
170 member of the td_thrinfo_t structure it returns.
171 The td_thr_set_event() and td_thr_clear_event() functions set and
174 clear, respectively, a set of event types in the event mask associated
175 with the thread th_p. To inspect a thread's event mask, call
176 td_thr_getinfo() for the thread and examine the ti_events member of the
177 td_thrinfo_t structure it returns.
178 The td_ta_set_event() and td_ta_clear_event() functions identical to
181 td_thr_set_event() and td_thr_clear_event(), respectively, except that
182 the target process's global event mask is modified. There is no provi‐
183 sion for inspecting the value of a target process's global event mask.
184 The td_thr_event_getmsg() function returns in *msg the event message
187 associated with thread *th_p. Reading a thread's event message consumes
188 the message, emptying the thread's event buffer. As noted above, each
189 thread's event buffer holds at most one event message; if a thread
190 reports a second event before the first event message has been read,
191 the second event message overwrites the first.
192 The td_ta_event_getmsg() function is identical to
195 td_thr_event_getmsg(), except that it is passed a process handle rather
196 than a thread handle. It selects some thread that has an event message
197 buffered and returns that thread's message. The thread selected is
198 undefined, except that as long as at least one thread has an event mes‐
199 sage buffered, it returns an event message from some such thread.
200 Event Set Manipulation Macros
202 Several macros are provided for manipulating event sets of type
203 td_thr_events_t:
204 td_event_emptyset Sets its argument to the NULL event set.
206 td_event_fillset Sets its argument to the set of all events.
209 td_event_addset Adds a specific event type to an event set.
212 td_event_delset Deletes a specific event type from an event set.
215 td_eventismember Tests whether a specific event type is a member
218 of an event set.
219 td_eventisempty Tests whether an event set is the NULL set.
222
225 The following values may be returned for all thread event routines:
226 TD_OK The call returned successfully.
228 TD_BADTH An invalid thread handle was passed in.
231 TD_BADTA An invalid internal process handle was passed.
234 TD_BADPH There is a NULL external process handle associated with
237 this internal process handle.
238 TD_DBERR A call to one of the imported interface routines failed.
241 TD_NOMSG No event message was available to return to
244 td_thr_event_getmsg() or td_ta_event_getmsg().
245 TD_ERR Some other parameter error occurred, or a libc_db() inter‐
248 nal error occurred.
249 The following value can be returned for td_thr_event_enable(),
253 td_thr_set_event(), and td_thr_clear_event() only:
254 TD_NOCAPAB Because the agent thread in the target process has not
256 completed initialization, this operation cannot be per‐
257 formed. The operation can be performed after the target
258 process has been allowed to make some forward progress.
259 See libc_db(3LIB).
260
263 See attributes(5) for description of the following attributes:
264 ┌─────────────────────────────┬─────────────────────────────┐
269 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
270 ├─────────────────────────────┼─────────────────────────────┤
271 │MT-Level │Safe │
272 └─────────────────────────────┴─────────────────────────────┘
273
275 libc_db(3LIB), attributes(5)
276SunOS 5.11 19 Oct 1998 td_ta_event_addr(3C_DB)