usr/src/man/man3c_db/td_ta_event_addr.3c_db

   1 '\" te
   2 .\"  Copyright (c) 1998 Sun Microsystems, Inc.  All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH TD_TA_EVENT_ADDR 3C_DB "Oct 19, 1998"
   7 .SH NAME
   8 td_ta_event_addr, td_thr_event_enable, td_ta_set_event, td_thr_set_event,
   9 td_ta_clear_event, td_thr_clear_event, td_ta_event_getmsg, td_thr_event_getmsg,
  10 td_event_emptyset, td_event_fillset, td_event_addset, td_event_delset,
  11 td_eventismember, td_eventisempty \- thread events in libc_db
  12 .SH SYNOPSIS
  13 .LP
  14 .nf
  15 cc [ \fIflag\fR... ] \fIfile\fR...  -lc_db  [ \fIlibrary\fR... ]
  16 #include <proc_service.h>
  17 #include <thread_db.h>
  18
  19 \fBtd_err_e\fR \fBtd_ta_event_addr\fR(\fBconst td_thragent_t *\fR\fIta_p\fR, \fBu_long event,td_notify_t *\fR\fInotify_p\fR);
  20 .fi
  21
  22 .LP
  23 .nf
  24 \fBtd_err_e\fR \fBtd_thr_event_enable\fR(\fBconst td_thrhandle_t *\fR\fIth_p\fR, \fBint\fR \fIon_off\fR);
  25 .fi
  26
  27 .LP
  28 .nf
  29 \fBtd_err_e\fR \fBtd_thr_set_event\fR(\fBconst td_thrhandle_t *\fR\fIth_p\fR, \fBtd_thr_events_t *\fR\fIevents\fR);
  30 .fi
  31
  32 .LP
  33 .nf
  34 \fBtd_err_e\fR \fBtd_ta_set_event\fR(\fBconst td_thragent_t *\fR\fIta_p\fR, \fBtd_thr_events_t *\fR\fIevents\fR);
  35 .fi
  36
  37 .LP
  38 .nf
  39 \fBtd_err_e\fR \fBtd_thr_clear_event\fR(\fBconst td_thrhandle_t *\fR\fIth_p\fR, \fBtd_thr_events_t *\fR\fIevents\fR);
  40 .fi
  41
  42 .LP
  43 .nf
  44 \fBtd_err_e\fR \fBtd_ta_clear_event\fR(\fBconst td_thragent_t *\fR\fIta_p\fR, \fBtd_thr_events_t *\fR\fIevents\fR);
  45 .fi
  46
  47 .LP
  48 .nf
  49 \fBtd_err_e\fR \fBtd_thr_event_getmsg\fR(\fBconst td_thrhandle_t *\fR\fIth_p\fR, \fBtd_event_msg_t *\fR\fImsg\fR);
  50 .fi
  51
  52 .LP
  53 .nf
  54 \fBtd_err_e\fR \fBtd_ta_event_getmsg\fR(\fBconst td_thragent_t *\fR\fIta_p\fR, \fBtd_event_msg_t *\fR\fImsg\fR);
  55 .fi
  56
  57 .LP
  58 .nf
  59 \fBvoid\fR \fBtd_event_emptyset\fR(\fBtd_thr_events_t\fR  *);
  60 .fi
  61
  62 .LP
  63 .nf
  64 \fBvoid\fR \fBtd_event_fillset\fR(\fBtd_thr_events_t\fR *);
  65 .fi
  66
  67 .LP
  68 .nf
  69 \fBvoid\fR \fBtd_event_addset\fR(\fBtd_thr_events_t\fR \fI*\fR, \fBtd_thr_events_e\fR\fI n\fR);
  70 .fi
  71
  72 .LP
  73 .nf
  74 \fBvoid\fR \fBtd_event_delset\fR(\fBtd_thr_events_t\fR \fI*\fR, \fBtd_thr_events_e\fR\fI n\fR);
  75 .fi
  76
  77 .LP
  78 .nf
  79 \fBvoid\fR \fBtd_eventismember\fR(\fBtd_thr_events_t\fR \fI*\fR, \fBtd_thr_events_e\fR\fI n\fR);
  80 .fi
  81
  82 .LP
  83 .nf
  84 \fBvoid\fR \fBtd_eventisempty\fR(\fBtd_thr_events_t\fR\fI*\fR);
  85 .fi
  86
  87 .SH DESCRIPTION
  88 .sp
  89 .LP
  90 These functions comprise the thread event facility for \fBlibc_db\fR(3LIB).
  91 This facility allows the controlling process to be notified when certain
  92 thread-related events occur in a target process and to retrieve information
  93 associated with these events.  An event consists of an event type, and
  94 optionally, some  associated event data, depending on the event type. See the
  95 section  titled "Event Set Manipulation Macros" that follows.
  96 .sp
  97 .LP
  98 The event type  and the associated event data, if any, constitute an "event
  99 message."   "Reporting an event" means delivering  an event message to the
 100 controlling process by way of \fBlibc_db\fR.
 101 .sp
 102 .LP
 103 Several flags can control event reporting, both a per-thread and per event
 104 basis. Event reporting may further be enabled  or disabled for a thread. There
 105 is not only a per-thread event mask that specifies which  event types should be
 106 reported for that thread, but there is also  a global event mask that applies
 107 to all threads.
 108 .sp
 109 .LP
 110 An event is reported, if and only if, the executing thread has event reporting
 111 enabled, and either the event type is enabled in the executing thread's event
 112 mask, or the event type is enabled in the global event mask.
 113 .sp
 114 .LP
 115 Each thread has associated with it an event buffer in which it stores the most
 116 recent event message it has generated, the type of the most recent event that
 117 it reported, and, depending on the event type, some additional information
 118 related to that event.  See the section titled  "Event Set Manipulation Macros"
 119 for a description of the  \fBtd_thr_events_e\fR and \fBtd_event_msg_t\fR types
 120 and a list of the event types and the values reported with them. The thread
 121 handle, type \fBtd_thrhandle_t\fR, the event type, and the possible value,
 122 together constitute an event message. Each thread's event buffer holds at most
 123 one event message.
 124 .sp
 125 .LP
 126 Each event type has an event reporting address associated with it.  A thread
 127 reports an event by writing the event message into the thread's event buffer
 128 and having control reach the event reporting address for that event type.
 129 .sp
 130 .LP
 131 Typically, the controlling process sets a breakpoint at the event reporting
 132 address for one or more event types. When the breakpoint is hit, the
 133 controlling process knows that an event of the corresponding type has occurred.
 134 .sp
 135 .LP
 136 The event types, and the additional information, if any, reported with each
 137 event, are:
 138 .sp
 139 .ne 2
 140 .na
 141 \fB\fBTD_READY\fR\fR
 142 .ad
 143 .RS 18n
 144 The thread became ready to execute.
 145 .RE
 146
 147 .sp
 148 .ne 2
 149 .na
 150 \fB\fBTD_SLEEP\fR\fR
 151 .ad
 152 .RS 18n
 153 The thread has blocked on a synchronization object.
 154 .RE
 155
 156 .sp
 157 .ne 2
 158 .na
 159 \fB\fBTD_SWITCHTO\fR\fR
 160 .ad
 161 .RS 18n
 162 A runnable thread is being assigned to  \fBLWP.\fR
 163 .RE
 164
 165 .sp
 166 .ne 2
 167 .na
 168 \fB\fBTD_SWITCHFROM\fR\fR
 169 .ad
 170 .RS 18n
 171 A running thread is being removed from its  \fBLWP.\fR
 172 .RE
 173
 174 .sp
 175 .ne 2
 176 .na
 177 \fB\fBTD_LOCK_TRY\fR\fR
 178 .ad
 179 .RS 18n
 180 A thread is trying to get an unavailable lock.
 181 .RE
 182
 183 .sp
 184 .ne 2
 185 .na
 186 \fB\fBTD_CATCHSIG\fR\fR
 187 .ad
 188 .RS 18n
 189 A signal was posted to a thread.
 190 .RE
 191
 192 .sp
 193 .ne 2
 194 .na
 195 \fB\fBTD_IDLE\fR\fR
 196 .ad
 197 .RS 18n
 198 An \fBLWP\fR is becoming idle.
 199 .RE
 200
 201 .sp
 202 .ne 2
 203 .na
 204 \fB\fBTD_CREATE\fR\fR
 205 .ad
 206 .RS 18n
 207 A thread is being created.
 208 .RE
 209
 210 .sp
 211 .ne 2
 212 .na
 213 \fB\fBTD_DEATH\fR\fR
 214 .ad
 215 .RS 18n
 216 A thread has terminated.
 217 .RE
 218
 219 .sp
 220 .ne 2
 221 .na
 222 \fB\fBTD_PREEMPT\fR\fR
 223 .ad
 224 .RS 18n
 225 A thread is being preempted.
 226 .RE
 227
 228 .sp
 229 .ne 2
 230 .na
 231 \fB\fBTD_PRI_INHERIT\fR\fR
 232 .ad
 233 .RS 18n
 234 A thread is inheriting an elevated priority from another thread.
 235 .RE
 236
 237 .sp
 238 .ne 2
 239 .na
 240 \fB\fBTD_REAP\fR\fR
 241 .ad
 242 .RS 18n
 243 A thread is being reaped.
 244 .RE
 245
 246 .sp
 247 .ne 2
 248 .na
 249 \fB\fBTD_CONCURRENCY\fR\fR
 250 .ad
 251 .RS 18n
 252 The number of \fBLWPs\fR is changing.
 253 .RE
 254
 255 .sp
 256 .ne 2
 257 .na
 258 \fB\fBTD_TIMEOUT\fR\fR
 259 .ad
 260 .RS 18n
 261 A condition-variable timed wait expired.
 262 .RE
 263
 264 .sp
 265 .LP
 266 The \fBtd_ta_event_addr()\fR function returns in *\fInotify_p\fR the event
 267 reporting address associated with event type \fBevent\fR. The controlling
 268 process may then set a breakpoint at that address.  If a thread hits that
 269 breakpoint, it reports an event of type  \fBevent\fR.
 270 .sp
 271 .LP
 272 The \fBtd_thr_event_enable()\fR function enables or disables event reporting
 273 for thread \fIth_p\fR. If a thread has event reporting disabled, it will not
 274 report any events. Threads are started with event reporting disabled.  Event
 275 reporting is enabled if  \fBon_off\fR is non-zero; otherwise, it is disabled.
 276 To determine whether or not event reporting is enabled  on a thread, call
 277 \fBtd_thr_getinfo()\fR for the thread and examine the \fBti_traceme\fR member
 278 of the \fBtd_thrinfo_t\fR structure it returns.
 279 .sp
 280 .LP
 281 The \fBtd_thr_set_event()\fR and \fBtd_thr_clear_event()\fR functions set and
 282 clear, respectively, a set of event types in the event mask associated with the
 283 thread \fIth_p\fR. To inspect a thread's event mask, call
 284 \fBtd_thr_getinfo()\fR for the thread and examine the \fBti_events\fR member of
 285 the \fBtd_thrinfo_t\fR structure it returns.
 286 .sp
 287 .LP
 288 The \fBtd_ta_set_event()\fR and \fBtd_ta_clear_event()\fR functions identical
 289 to \fBtd_thr_set_event()\fR and \fBtd_thr_clear_event()\fR, respectively,
 290 except that the target process's global event mask is  modified. There is no
 291 provision for inspecting the value of a  target process's global event mask.
 292 .sp
 293 .LP
 294 The \fBtd_thr_event_getmsg()\fR function returns in *\fImsg\fR the event
 295 message associated with thread *\fIth_p\fR. Reading a thread's event message
 296 consumes the message, emptying the thread's event buffer.  As noted above, each
 297 thread's event buffer holds at most one event message; if a thread reports a
 298 second event before the first event message has been read, the second event
 299 message overwrites the first.
 300 .sp
 301 .LP
 302 The \fBtd_ta_event_getmsg()\fR function is identical to
 303 \fBtd_thr_event_getmsg()\fR, except that it is passed a process handle rather
 304 than a thread handle. It selects some thread that has an event message buffered
 305 and returns that thread's message.  The thread selected is undefined, except
 306 that as long as at least one thread has an event message buffered, it returns
 307 an event message from some such thread.
 308 .SS "Event Set Manipulation Macros"
 309 .sp
 310 .LP
 311 Several macros are provided for manipulating event sets of type
 312 \fBtd_thr_events_t\fR:
 313 .sp
 314 .ne 2
 315 .na
 316 \fB\fBtd_event_emptyset\fR \fR
 317 .ad
 318 .RS 22n
 319 Sets its argument to the \fINULL\fR event set.
 320 .RE
 321
 322 .sp
 323 .ne 2
 324 .na
 325 \fB\fBtd_event_fillset\fR\fR
 326 .ad
 327 .RS 22n
 328 Sets its argument to the set of all events.
 329 .RE
 330
 331 .sp
 332 .ne 2
 333 .na
 334 \fB\fBtd_event_addset\fR\fR
 335 .ad
 336 .RS 22n
 337 Adds a specific event type to an event set.
 338 .RE
 339
 340 .sp
 341 .ne 2
 342 .na
 343 \fB\fBtd_event_delset\fR\fR
 344 .ad
 345 .RS 22n
 346 Deletes a specific event type from an event set.
 347 .RE
 348
 349 .sp
 350 .ne 2
 351 .na
 352 \fB\fBtd_eventismember\fR\fR
 353 .ad
 354 .RS 22n
 355 Tests whether a specific event type is a member of an event set.
 356 .RE
 357
 358 .sp
 359 .ne 2
 360 .na
 361 \fB\fBtd_eventisempty\fR\fR
 362 .ad
 363 .RS 22n
 364 Tests whether an event set is the \fINULL\fR set.
 365 .RE
 366
 367 .SH RETURN VALUES
 368 .sp
 369 .LP
 370 The following values may be returned for all thread event routines:
 371 .sp
 372 .ne 2
 373 .na
 374 \fB\fBTD_OK\fR\fR
 375 .ad
 376 .RS 12n
 377 The call returned successfully.
 378 .RE
 379
 380 .sp
 381 .ne 2
 382 .na
 383 \fB\fBTD_BADTH\fR\fR
 384 .ad
 385 .RS 12n
 386 An invalid thread handle was passed in.
 387 .RE
 388
 389 .sp
 390 .ne 2
 391 .na
 392 \fB\fBTD_BADTA\fR\fR
 393 .ad
 394 .RS 12n
 395 An invalid internal process handle was passed.
 396 .RE
 397
 398 .sp
 399 .ne 2
 400 .na
 401 \fB\fBTD_BADPH\fR\fR
 402 .ad
 403 .RS 12n
 404 There is a \fINULL\fR external process handle associated with this internal
 405 process handle.
 406 .RE
 407
 408 .sp
 409 .ne 2
 410 .na
 411 \fB\fBTD_DBERR\fR\fR
 412 .ad
 413 .RS 12n
 414 A call to one of the imported interface routines failed.
 415 .RE
 416
 417 .sp
 418 .ne 2
 419 .na
 420 \fB\fBTD_NOMSG\fR\fR
 421 .ad
 422 .RS 12n
 423 No event message was available to return to \fBtd_thr_event_getmsg()\fR or
 424 \fBtd_ta_event_getmsg()\fR.
 425 .RE
 426
 427 .sp
 428 .ne 2
 429 .na
 430 \fB\fBTD_ERR\fR\fR
 431 .ad
 432 .RS 12n
 433 Some other parameter error occurred, or a  \fBlibc_db()\fR internal error
 434 occurred.
 435 .RE
 436
 437 .sp
 438 .LP
 439 The following value can be returned for \fBtd_thr_event_enable()\fR,
 440 \fBtd_thr_set_event()\fR, and \fBtd_thr_clear_event()\fR only:
 441 .sp
 442 .ne 2
 443 .na
 444 \fB\fBTD_NOCAPAB\fR \fR
 445 .ad
 446 .RS 15n
 447 Because the agent thread in the target process has not completed
 448 initialization, this operation cannot be performed. The operation can be
 449 performed after the target process has been allowed to make some forward
 450 progress.  See \fBlibc_db\fR(3LIB).
 451 .RE
 452
 453 .SH ATTRIBUTES
 454 .sp
 455 .LP
 456 See \fBattributes\fR(5) for description of the following attributes:
 457 .sp
 458
 459 .sp
 460 .TS
 461 box;
 462 c | c
 463 l | l .
 464 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 465 _
 466 MT-Level        Safe
 467 .TE
 468
 469 .SH SEE ALSO
 470 .sp
 471 .LP
 472 \fBlibc_db\fR(3LIB), \fBattributes\fR(5)