1td_ta_event_addr(3C_DB)Threads Debugging Library Functiontsd_ta_event_addr(3C_DB)
2
3
4

NAME

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

SYNOPSIS

13       cc [ flag... ] file...  -lc_db  [ library... ]
14       #include <proc_service.h>
15       #include <thread_db.h>
16
17       td_err_e td_ta_event_addr(const td_thragent_t *ta_p, u_long event,td_notify_t *notify_p);
18
19
20       td_err_e td_thr_event_enable(const td_thrhandle_t *th_p, int on_off);
21
22
23       td_err_e td_thr_set_event(const td_thrhandle_t *th_p, td_thr_events_t *events);
24
25
26       td_err_e td_ta_set_event(const td_thragent_t *ta_p, td_thr_events_t *events);
27
28
29       td_err_e td_thr_clear_event(const td_thrhandle_t *th_p, td_thr_events_t *events);
30
31
32       td_err_e td_ta_clear_event(const td_thragent_t *ta_p, td_thr_events_t *events);
33
34
35       td_err_e td_thr_event_getmsg(const td_thrhandle_t *th_p, td_event_msg_t *msg);
36
37
38       td_err_e td_ta_event_getmsg(const td_thragent_t *ta_p, td_event_msg_t *msg);
39
40
41       void td_event_emptyset(td_thr_events_t  *);
42
43
44       void td_event_fillset(td_thr_events_t *);
45
46
47       void td_event_addset(td_thr_events_t *, td_thr_events_e n);
48
49
50       void td_event_delset(td_thr_events_t *, td_thr_events_e n);
51
52
53       void td_eventismember(td_thr_events_t *, td_thr_events_e n);
54
55
56       void td_eventisempty(td_thr_events_t*);
57
58

DESCRIPTION

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
68
69       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
73
74       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
80
81       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
86
87       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
98
99       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
104
105       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
110
111       The  event types, and the additional information, if any, reported with
112       each event, are:
113
114       TD_READY          The thread became ready to execute.
115
116
117       TD_SLEEP          The thread has blocked on a synchronization object.
118
119
120       TD_SWITCHTO       A runnable thread is being assigned to  LWP.
121
122
123       TD_SWITCHFROM     A running thread is being removed from its  LWP.
124
125
126       TD_LOCK_TRY       A thread is trying to get an unavailable lock.
127
128
129       TD_CATCHSIG       A signal was posted to a thread.
130
131
132       TD_IDLE           An LWP is becoming idle.
133
134
135       TD_CREATE         A thread is being created.
136
137
138       TD_DEATH          A thread has terminated.
139
140
141       TD_PREEMPT        A thread is being preempted.
142
143
144       TD_PRI_INHERIT    A thread is  inheriting  an  elevated  priority  from
145                         another thread.
146
147
148       TD_REAP           A thread is being reaped.
149
150
151       TD_CONCURRENCY    The number of LWPs is changing.
152
153
154       TD_TIMEOUT        A condition-variable timed wait expired.
155
156
157
158       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
163
164       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
172
173       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
179
180       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
185
186       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
193
194       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
201   Event Set Manipulation Macros
202       Several  macros  are  provided  for  manipulating  event  sets  of type
203       td_thr_events_t:
204
205       td_event_emptyset     Sets its argument to the NULL event set.
206
207
208       td_event_fillset      Sets its argument to the set of all events.
209
210
211       td_event_addset       Adds a specific event type to an event set.
212
213
214       td_event_delset       Deletes a specific event type from an event set.
215
216
217       td_eventismember      Tests whether a specific event type is  a  member
218                             of an event set.
219
220
221       td_eventisempty       Tests whether an event set is the NULL set.
222
223

RETURN VALUES

225       The following values may be returned for all thread event routines:
226
227       TD_OK       The call returned successfully.
228
229
230       TD_BADTH    An invalid thread handle was passed in.
231
232
233       TD_BADTA    An invalid internal process handle was passed.
234
235
236       TD_BADPH    There  is  a  NULL  external process handle associated with
237                   this internal process handle.
238
239
240       TD_DBERR    A call to one of the imported interface routines failed.
241
242
243       TD_NOMSG    No   event   message   was   available   to    return    to
244                   td_thr_event_getmsg() or td_ta_event_getmsg().
245
246
247       TD_ERR      Some other parameter error occurred, or a  libc_db() inter‐
248                   nal error occurred.
249
250
251
252       The  following  value  can  be  returned   for   td_thr_event_enable(),
253       td_thr_set_event(), and td_thr_clear_event() only:
254
255       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
261

ATTRIBUTES

263       See attributes(5) for description of the following attributes:
264
265
266
267
268       ┌─────────────────────────────┬─────────────────────────────┐
269       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
270       ├─────────────────────────────┼─────────────────────────────┤
271       │MT-Level                     │Safe                         │
272       └─────────────────────────────┴─────────────────────────────┘
273

SEE ALSO

275       libc_db(3LIB), attributes(5)
276
277
278
279SunOS 5.11                        19 Oct 1998          td_ta_event_addr(3C_DB)
Impressum