GDBserver
glibc_thread_db.h
Go to the documentation of this file.
1 /* thread_db.h -- interface to libthread_db.so library for debugging -lpthread
2  Copyright (C) 1999-2013 Free Software Foundation, Inc.
3  This file is part of the GNU C Library.
4 
5  The GNU C Library is free software; you can redistribute it and/or
6  modify it under the terms of the GNU Lesser General Public
7  License as published by the Free Software Foundation; either
8  version 2.1 of the License, or (at your option) any later version.
9 
10  The GNU C Library is distributed in the hope that it will be useful,
11  but WITHOUT ANY WARRANTY; without even the implied warranty of
12  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13  Lesser General Public License for more details.
14 
15  You should have received a copy of the GNU Lesser General Public
16  License along with the GNU C Library; if not, see
17  <http://www.gnu.org/licenses/>. */
18 
19 #ifndef _THREAD_DB_H
20 #define _THREAD_DB_H 1
21 
22 /* This is the debugger interface for the NPTL library. It is
23  modelled closely after the interface with same names in Solaris
24  with the goal to share the same code in the debugger. */
25 #include <pthread.h>
26 #include <stdint.h>
27 #include <sys/types.h>
28 #include <sys/procfs.h>
29 
30 
31 /* Error codes of the library. */
32 typedef enum
33 {
34  TD_OK, /* No error. */
35  TD_ERR, /* No further specified error. */
36  TD_NOTHR, /* No matching thread found. */
37  TD_NOSV, /* No matching synchronization handle found. */
38  TD_NOLWP, /* No matching light-weighted process found. */
39  TD_BADPH, /* Invalid process handle. */
40  TD_BADTH, /* Invalid thread handle. */
41  TD_BADSH, /* Invalid synchronization handle. */
42  TD_BADTA, /* Invalid thread agent. */
43  TD_BADKEY, /* Invalid key. */
44  TD_NOMSG, /* No event available. */
45  TD_NOFPREGS, /* No floating-point register content available. */
46  TD_NOLIBTHREAD, /* Application not linked with thread library. */
47  TD_NOEVENT, /* Requested event is not supported. */
48  TD_NOCAPAB, /* Capability not available. */
49  TD_DBERR, /* Internal debug library error. */
50  TD_NOAPLIC, /* Operation is not applicable. */
51  TD_NOTSD, /* No thread-specific data available. */
52  TD_MALLOC, /* Out of memory. */
53  TD_PARTIALREG, /* Not entire register set was read or written. */
54  TD_NOXREGS, /* X register set not available for given thread. */
55  TD_TLSDEFER, /* Thread has not yet allocated TLS for given module. */
57  TD_VERSION, /* Version if libpthread and libthread_db do not match. */
58  TD_NOTLS /* There is no TLS segment in the given module. */
59 } td_err_e;
60 
61 
62 /* Possible thread states. TD_THR_ANY_STATE is a pseudo-state used to
63  select threads regardless of state in td_ta_thr_iter(). */
64 typedef enum
65 {
75 
76 /* Thread type: user or system. TD_THR_ANY_TYPE is a pseudo-type used
77  to select threads regardless of type in td_ta_thr_iter(). */
78 typedef enum
79 {
84 
85 
86 /* Types of the debugging library. */
87 
88 /* Handle for a process. This type is opaque. */
89 typedef struct td_thragent td_thragent_t;
90 
91 /* The actual thread handle type. This is also opaque. */
92 typedef struct td_thrhandle
93 {
97 
98 
99 /* Forward declaration of a type defined by and for the dynamic linker. */
100 struct link_map;
101 
102 
103 /* Flags for `td_ta_thr_iter'. */
104 #define TD_THR_ANY_USER_FLAGS 0xffffffff
105 #define TD_THR_LOWEST_PRIORITY -20
106 #define TD_SIGNO_MASK NULL
107 
108 
109 #define TD_EVENTSIZE 2
110 #define BT_UISHIFT 5 /* log base 2 of BT_NBIPUI, to extract word index */
111 #define BT_NBIPUI (1 << BT_UISHIFT) /* n bits per uint */
112 #define BT_UIMASK (BT_NBIPUI - 1) /* to extract bit index */
113 
114 /* Bitmask of enabled events. */
115 typedef struct td_thr_events
116 {
119 
120 /* Event set manipulation macros. */
121 #define __td_eventmask(n) \
122  (UINT32_C (1) << (((n) - 1) & BT_UIMASK))
123 #define __td_eventword(n) \
124  ((UINT32_C ((n) - 1)) >> BT_UISHIFT)
125 
126 #define td_event_emptyset(setp) \
127  do { \
128  int __i; \
129  for (__i = TD_EVENTSIZE; __i > 0; --__i) \
130  (setp)->event_bits[__i - 1] = 0; \
131  } while (0)
132 
133 #define td_event_fillset(setp) \
134  do { \
135  int __i; \
136  for (__i = TD_EVENTSIZE; __i > 0; --__i) \
137  (setp)->event_bits[__i - 1] = UINT32_C (0xffffffff); \
138  } while (0)
139 
140 #define td_event_addset(setp, n) \
141  (((setp)->event_bits[__td_eventword (n)]) |= __td_eventmask (n))
142 #define td_event_delset(setp, n) \
143  (((setp)->event_bits[__td_eventword (n)]) &= ~__td_eventmask (n))
144 #define td_eventismember(setp, n) \
145  (__td_eventmask (n) & ((setp)->event_bits[__td_eventword (n)]))
146 #if TD_EVENTSIZE == 2
147 # define td_eventisempty(setp) \
148  (!((setp)->event_bits[0]) && !((setp)->event_bits[1]))
149 #else
150 # error "td_eventisempty must be changed to match TD_EVENTSIZE"
151 #endif
152 
153 /* Events reportable by the thread implementation. */
154 typedef enum
155 {
156  TD_ALL_EVENTS, /* Pseudo-event number. */
157  TD_EVENT_NONE = TD_ALL_EVENTS, /* Depends on context. */
158  TD_READY, /* Is executable now. */
159  TD_SLEEP, /* Blocked in a synchronization obj. */
160  TD_SWITCHTO, /* Now assigned to a process. */
161  TD_SWITCHFROM, /* Not anymore assigned to a process. */
162  TD_LOCK_TRY, /* Trying to get an unavailable lock. */
163  TD_CATCHSIG, /* Signal posted to the thread. */
164  TD_IDLE, /* Process getting idle. */
165  TD_CREATE, /* New thread created. */
166  TD_DEATH, /* Thread terminated. */
167  TD_PREEMPT, /* Preempted. */
168  TD_PRI_INHERIT, /* Inherited elevated priority. */
169  TD_REAP, /* Reaped. */
170  TD_CONCURRENCY, /* Number of processes changing. */
171  TD_TIMEOUT, /* Conditional variable wait timed out. */
174  TD_EVENTS_ENABLE = 31 /* Event reporting enabled. */
175 } td_event_e;
176 
177 /* Values representing the different ways events are reported. */
178 typedef enum
179 {
180  NOTIFY_BPT, /* User must insert breakpoint at u.bptaddr. */
181  NOTIFY_AUTOBPT, /* Breakpoint at u.bptaddr is automatically
182  inserted. */
183  NOTIFY_SYSCALL /* System call u.syscallno will be invoked. */
184 } td_notify_e;
185 
186 /* Description how event type is reported. */
187 typedef struct td_notify
188 {
189  td_notify_e type; /* Way the event is reported. */
190  union
191  {
192  psaddr_t bptaddr; /* Address of breakpoint. */
193  int syscallno; /* Number of system call used. */
194  } u;
195 } td_notify_t;
196 
197 /* Structure used to report event. */
198 typedef struct td_event_msg
199 {
200  td_event_e event; /* Event type being reported. */
201  const td_thrhandle_t *th_p; /* Thread reporting the event. */
202  union
203  {
204 # if 0
205  td_synchandle_t *sh; /* Handle of synchronization object. */
206 #endif
207  uintptr_t data; /* Event specific data. */
208  } msg;
210 
211 /* Structure containing event data available in each thread structure. */
212 typedef struct
213 {
214  td_thr_events_t eventmask; /* Mask of enabled events. */
215  td_event_e eventnum; /* Number of last event. */
216  void *eventdata; /* Data associated with event. */
217 } td_eventbuf_t;
218 
219 
220 /* Gathered statistics about the process. */
221 typedef struct td_ta_stats
222 {
223  int nthreads; /* Total number of threads in use. */
224  int r_concurrency; /* Concurrency level requested by user. */
225  int nrunnable_num; /* Average runnable threads, numerator. */
226  int nrunnable_den; /* Average runnable threads, denominator. */
227  int a_concurrency_num; /* Achieved concurrency level, numerator. */
228  int a_concurrency_den; /* Achieved concurrency level, denominator. */
229  int nlwps_num; /* Average number of processes in use,
230  numerator. */
231  int nlwps_den; /* Average number of processes in use,
232  denominator. */
233  int nidle_num; /* Average number of idling processes,
234  numerator. */
235  int nidle_den; /* Average number of idling processes,
236  denominator. */
237 } td_ta_stats_t;
238 
239 
240 /* Since Sun's library is based on Solaris threads we have to define a few
241  types to map them to POSIX threads. */
242 typedef pthread_t thread_t;
243 typedef pthread_key_t thread_key_t;
244 
245 
246 /* Callback for iteration over threads. */
247 typedef int td_thr_iter_f (const td_thrhandle_t *, void *);
248 
249 /* Callback for iteration over thread local data. */
250 typedef int td_key_iter_f (thread_key_t, void (*) (void *), void *);
251 
252 
253 
254 /* Forward declaration. This has to be defined by the user. */
255 struct ps_prochandle;
256 
257 
258 /* Information about the thread. */
259 typedef struct td_thrinfo
260 {
261  td_thragent_t *ti_ta_p; /* Process handle. */
262  unsigned int ti_user_flags; /* Unused. */
263  thread_t ti_tid; /* Thread ID returned by
264  pthread_create(). */
265  char *ti_tls; /* Pointer to thread-local data. */
266  psaddr_t ti_startfunc; /* Start function passed to
267  pthread_create(). */
268  psaddr_t ti_stkbase; /* Base of thread's stack. */
269  long int ti_stksize; /* Size of thread's stack. */
270  psaddr_t ti_ro_area; /* Unused. */
271  int ti_ro_size; /* Unused. */
272  td_thr_state_e ti_state; /* Thread state. */
273  unsigned char ti_db_suspended; /* Nonzero if suspended by debugger. */
274  td_thr_type_e ti_type; /* Type of the thread (system vs
275  user thread). */
276  intptr_t ti_pc; /* Unused. */
277  intptr_t ti_sp; /* Unused. */
278  short int ti_flags; /* Unused. */
279  int ti_pri; /* Thread priority. */
280  lwpid_t ti_lid; /* Kernel PID for this thread. */
281  sigset_t ti_sigmask; /* Signal mask. */
282  unsigned char ti_traceme; /* Nonzero if event reporting
283  enabled. */
284  unsigned char ti_preemptflag; /* Unused. */
285  unsigned char ti_pirecflag; /* Unused. */
286  sigset_t ti_pending; /* Set of pending signals. */
287  td_thr_events_t ti_events; /* Set of enabled events. */
288 } td_thrinfo_t;
289 
290 
291 
292 /* Prototypes for exported library functions. */
293 
294 /* Initialize the thread debug support library. */
295 extern td_err_e td_init (void);
296 
297 /* Historical relict. Should not be used anymore. */
298 extern td_err_e td_log (void);
299 
300 /* Return list of symbols the library can request. */
301 extern const char **td_symbol_list (void);
302 
303 /* Generate new thread debug library handle for process PS. */
304 extern td_err_e td_ta_new (struct ps_prochandle *__ps, td_thragent_t **__ta);
305 
306 /* Free resources allocated for TA. */
307 extern td_err_e td_ta_delete (td_thragent_t *__ta);
308 
309 /* Get number of currently running threads in process associated with TA. */
310 extern td_err_e td_ta_get_nthreads (const td_thragent_t *__ta, int *__np);
311 
312 /* Return process handle passed in `td_ta_new' for process associated with
313  TA. */
314 extern td_err_e td_ta_get_ph (const td_thragent_t *__ta,
315  struct ps_prochandle **__ph);
316 
317 /* Map thread library handle PT to thread debug library handle for process
318  associated with TA and store result in *TH. */
319 extern td_err_e td_ta_map_id2thr (const td_thragent_t *__ta, pthread_t __pt,
320  td_thrhandle_t *__th);
321 
322 /* Map process ID LWPID to thread debug library handle for process
323  associated with TA and store result in *TH. */
324 extern td_err_e td_ta_map_lwp2thr (const td_thragent_t *__ta, lwpid_t __lwpid,
325  td_thrhandle_t *__th);
326 
327 
328 /* Call for each thread in a process associated with TA the callback function
329  CALLBACK. */
330 extern td_err_e td_ta_thr_iter (const td_thragent_t *__ta,
331  td_thr_iter_f *__callback, void *__cbdata_p,
332  td_thr_state_e __state, int __ti_pri,
333  sigset_t *__ti_sigmask_p,
334  unsigned int __ti_user_flags);
335 
336 /* Call for each defined thread local data entry the callback function KI. */
337 extern td_err_e td_ta_tsd_iter (const td_thragent_t *__ta, td_key_iter_f *__ki,
338  void *__p);
339 
340 
341 /* Get event address for EVENT. */
342 extern td_err_e td_ta_event_addr (const td_thragent_t *__ta,
343  td_event_e __event, td_notify_t *__ptr);
344 
345 /* Enable EVENT in global mask. */
346 extern td_err_e td_ta_set_event (const td_thragent_t *__ta,
347  td_thr_events_t *__event);
348 
349 /* Disable EVENT in global mask. */
350 extern td_err_e td_ta_clear_event (const td_thragent_t *__ta,
351  td_thr_events_t *__event);
352 
353 /* Return information about last event. */
354 extern td_err_e td_ta_event_getmsg (const td_thragent_t *__ta,
355  td_event_msg_t *__msg);
356 
357 
358 /* Set suggested concurrency level for process associated with TA. */
359 extern td_err_e td_ta_setconcurrency (const td_thragent_t *__ta, int __level);
360 
361 
362 /* Enable collecting statistics for process associated with TA. */
363 extern td_err_e td_ta_enable_stats (const td_thragent_t *__ta, int __enable);
364 
365 /* Reset statistics. */
366 extern td_err_e td_ta_reset_stats (const td_thragent_t *__ta);
367 
368 /* Retrieve statistics from process associated with TA. */
369 extern td_err_e td_ta_get_stats (const td_thragent_t *__ta,
370  td_ta_stats_t *__statsp);
371 
372 
373 /* Validate that TH is a thread handle. */
374 extern td_err_e td_thr_validate (const td_thrhandle_t *__th);
375 
376 /* Return information about thread TH. */
377 extern td_err_e td_thr_get_info (const td_thrhandle_t *__th,
378  td_thrinfo_t *__infop);
379 
380 /* Retrieve floating-point register contents of process running thread TH. */
381 extern td_err_e td_thr_getfpregs (const td_thrhandle_t *__th,
382  prfpregset_t *__regset);
383 
384 /* Retrieve general register contents of process running thread TH. */
385 extern td_err_e td_thr_getgregs (const td_thrhandle_t *__th,
386  prgregset_t __gregs);
387 
388 /* Retrieve extended register contents of process running thread TH. */
389 extern td_err_e td_thr_getxregs (const td_thrhandle_t *__th, void *__xregs);
390 
391 /* Get size of extended register set of process running thread TH. */
392 extern td_err_e td_thr_getxregsize (const td_thrhandle_t *__th, int *__sizep);
393 
394 /* Set floating-point register contents of process running thread TH. */
395 extern td_err_e td_thr_setfpregs (const td_thrhandle_t *__th,
396  const prfpregset_t *__fpregs);
397 
398 /* Set general register contents of process running thread TH. */
399 extern td_err_e td_thr_setgregs (const td_thrhandle_t *__th,
400  prgregset_t __gregs);
401 
402 /* Set extended register contents of process running thread TH. */
403 extern td_err_e td_thr_setxregs (const td_thrhandle_t *__th,
404  const void *__addr);
405 
406 
407 /* Get address of the given module's TLS storage area for the given thread. */
408 extern td_err_e td_thr_tlsbase (const td_thrhandle_t *__th,
409  unsigned long int __modid,
410  psaddr_t *__base);
411 
412 /* Get address of thread local variable. */
413 extern td_err_e td_thr_tls_get_addr (const td_thrhandle_t *__th,
414  psaddr_t __map_address, size_t __offset,
415  psaddr_t *__address);
416 
417 
418 /* Enable reporting for EVENT for thread TH. */
419 extern td_err_e td_thr_event_enable (const td_thrhandle_t *__th, int __event);
420 
421 /* Enable EVENT for thread TH. */
422 extern td_err_e td_thr_set_event (const td_thrhandle_t *__th,
423  td_thr_events_t *__event);
424 
425 /* Disable EVENT for thread TH. */
426 extern td_err_e td_thr_clear_event (const td_thrhandle_t *__th,
427  td_thr_events_t *__event);
428 
429 /* Get event message for thread TH. */
430 extern td_err_e td_thr_event_getmsg (const td_thrhandle_t *__th,
431  td_event_msg_t *__msg);
432 
433 
434 /* Set priority of thread TH. */
435 extern td_err_e td_thr_setprio (const td_thrhandle_t *__th, int __prio);
436 
437 
438 /* Set pending signals for thread TH. */
439 extern td_err_e td_thr_setsigpending (const td_thrhandle_t *__th,
440  unsigned char __n, const sigset_t *__ss);
441 
442 /* Set signal mask for thread TH. */
443 extern td_err_e td_thr_sigsetmask (const td_thrhandle_t *__th,
444  const sigset_t *__ss);
445 
446 
447 /* Return thread local data associated with key TK in thread TH. */
448 extern td_err_e td_thr_tsd (const td_thrhandle_t *__th,
449  const thread_key_t __tk, void **__data);
450 
451 
452 /* Suspend execution of thread TH. */
453 extern td_err_e td_thr_dbsuspend (const td_thrhandle_t *__th);
454 
455 /* Resume execution of thread TH. */
456 extern td_err_e td_thr_dbresume (const td_thrhandle_t *__th);
457 
458 #endif /* thread_db.h */
unsigned int lwpid_t
td_err_e td_ta_setconcurrency(const td_thragent_t *__ta, int __level)
td_err_e td_thr_getxregs(const td_thrhandle_t *__th, void *__xregs)
psaddr_t ti_stkbase
td_thr_events_t eventmask
int td_key_iter_f(thread_key_t, void(*)(void *), void *)
td_err_e td_ta_get_nthreads(const td_thragent_t *__ta, int *__np)
psaddr_t bptaddr
td_err_e td_thr_event_enable(const td_thrhandle_t *__th, int __event)
td_err_e td_thr_dbresume(const td_thrhandle_t *__th)
struct td_ta_stats td_ta_stats_t
td_thr_type_e ti_type
td_err_e td_thr_setgregs(const td_thrhandle_t *__th, prgregset_t __gregs)
intptr_t ti_sp
td_err_e td_thr_setsigpending(const td_thrhandle_t *__th, unsigned char __n, const sigset_t *__ss)
td_notify_e type
td_err_e td_ta_get_ph(const td_thragent_t *__ta, struct ps_prochandle **__ph)
struct td_thrinfo td_thrinfo_t
td_err_e td_thr_getxregsize(const td_thrhandle_t *__th, int *__sizep)
thread_t ti_tid
td_err_e td_thr_setprio(const td_thrhandle_t *__th, int __prio)
pthread_key_t thread_key_t
td_thragent_t * ti_ta_p
sigset_t ti_pending
#define TD_EVENTSIZE
td_err_e td_ta_map_lwp2thr(const td_thragent_t *__ta, lwpid_t __lwpid, td_thrhandle_t *__th)
td_err_e td_thr_tlsbase(const td_thrhandle_t *__th, unsigned long int __modid, psaddr_t *__base)
td_err_e td_init(void)
td_err_e td_ta_reset_stats(const td_thragent_t *__ta)
td_err_e td_thr_getfpregs(const td_thrhandle_t *__th, prfpregset_t *__regset)
struct td_notify td_notify_t
td_thr_type_e
intptr_t ti_pc
const char ** td_symbol_list(void)
uint32_t event_bits[TD_EVENTSIZE]
struct td_thrhandle td_thrhandle_t
int td_thr_iter_f(const td_thrhandle_t *, void *)
td_err_e td_thr_sigsetmask(const td_thrhandle_t *__th, const sigset_t *__ss)
unsigned char ti_preemptflag
td_err_e td_thr_dbsuspend(const td_thrhandle_t *__th)
psaddr_t th_unique
struct td_thragent td_thragent_t
struct td_event_msg td_event_msg_t
unsigned char ti_traceme
sigset_t ti_sigmask
td_err_e td_ta_delete(td_thragent_t *__ta)
td_err_e td_ta_clear_event(const td_thragent_t *__ta, td_thr_events_t *__event)
td_err_e td_thr_getgregs(const td_thrhandle_t *__th, prgregset_t __gregs)
td_err_e td_ta_get_stats(const td_thragent_t *__ta, td_ta_stats_t *__statsp)
td_err_e td_ta_event_getmsg(const td_thragent_t *__ta, td_event_msg_t *__msg)
td_notify_e
td_thr_state_e
unsigned int ti_user_flags
void * psaddr_t
long int ti_stksize
pthread_t thread_t
union td_event_msg::@10 msg
td_err_e td_ta_enable_stats(const td_thragent_t *__ta, int __enable)
td_err_e td_ta_tsd_iter(const td_thragent_t *__ta, td_key_iter_f *__ki, void *__p)
td_event_e
td_err_e td_thr_setxregs(const td_thrhandle_t *__th, const void *__addr)
td_thragent_t * th_ta_p
td_err_e td_ta_thr_iter(const td_thragent_t *__ta, td_thr_iter_f *__callback, void *__cbdata_p, td_thr_state_e __state, int __ti_pri, sigset_t *__ti_sigmask_p, unsigned int __ti_user_flags)
td_err_e td_thr_validate(const td_thrhandle_t *__th)
td_event_e eventnum
uintptr_t data
union td_notify::@9 u
td_err_e td_ta_set_event(const td_thragent_t *__ta, td_thr_events_t *__event)
elf_fpregset_t prfpregset_t
td_err_e td_thr_get_info(const td_thrhandle_t *__th, td_thrinfo_t *__infop)
td_err_e td_ta_new(struct ps_prochandle *__ps, td_thragent_t **__ta)
td_err_e td_thr_event_getmsg(const td_thrhandle_t *__th, td_event_msg_t *__msg)
td_err_e td_thr_setfpregs(const td_thrhandle_t *__th, const prfpregset_t *__fpregs)
td_err_e td_ta_event_addr(const td_thragent_t *__ta, td_event_e __event, td_notify_t *__ptr)
td_err_e td_thr_set_event(const td_thrhandle_t *__th, td_thr_events_t *__event)
td_err_e td_ta_map_id2thr(const td_thragent_t *__ta, pthread_t __pt, td_thrhandle_t *__th)
struct td_thr_events td_thr_events_t
td_err_e td_thr_tls_get_addr(const td_thrhandle_t *__th, psaddr_t __map_address, size_t __offset, psaddr_t *__address)
td_err_e td_thr_clear_event(const td_thrhandle_t *__th, td_thr_events_t *__event)
elf_gregset_t prgregset_t
short int ti_flags
td_err_e td_log(void)
td_thr_events_t ti_events
psaddr_t ti_ro_area
const td_thrhandle_t * th_p
td_err_e td_thr_tsd(const td_thrhandle_t *__th, const thread_key_t __tk, void **__data)
td_event_e event
td_thr_state_e ti_state
unsigned char ti_db_suspended
unsigned char ti_pirecflag
psaddr_t ti_startfunc
lwpid_t ti_lid
td_err_e