1 #ifdef HAVE_THREAD_DB_H
4 #ifndef LIBTHREAD_DB_SO
5 #define LIBTHREAD_DB_SO "libthread_db.so.1"
8 #ifndef LIBTHREAD_DB_SEARCH_PATH
9 #define LIBTHREAD_DB_SEARCH_PATH ""
14 /* Copyright (C) 1999, 2000, 2007, 2008, 2009, 2010, 2011
15 Free Software Foundation, Inc.
16 This file is part of the GNU C Library.
18 The GNU C Library is free software; you can redistribute it and/or
19 modify it under the terms of the GNU Library General Public License as
20 published by the Free Software Foundation; either version 3 of the
21 License, or (at your option) any later version.
23 The GNU C Library is distributed in the hope that it will be useful,
24 but WITHOUT ANY WARRANTY; without even the implied warranty of
25 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
26 Library General Public License for more details.
28 You should have received a copy of the GNU General Public License
29 along with this program. If not, see <http://www.gnu.org/licenses/>. */
32 #define _THREAD_DB_H 1
34 /* This is the debugger interface for the LinuxThreads library. It is
35 modelled closely after the interface with same names in Solaris with
36 the goal to share the same code in the debugger. */
38 #include <sys/types.h>
39 #include <sys/procfs.h>
42 /* Error codes of the library. */
45 TD_OK
, /* No error. */
46 TD_ERR
, /* No further specified error. */
47 TD_NOTHR
, /* No matching thread found. */
48 TD_NOSV
, /* No matching synchronization handle found. */
49 TD_NOLWP
, /* No matching light-weighted process found. */
50 TD_BADPH
, /* Invalid process handle. */
51 TD_BADTH
, /* Invalid thread handle. */
52 TD_BADSH
, /* Invalid synchronization handle. */
53 TD_BADTA
, /* Invalid thread agent. */
54 TD_BADKEY
, /* Invalid key. */
55 TD_NOMSG
, /* No event available. */
56 TD_NOFPREGS
, /* No floating-point register content available. */
57 TD_NOLIBTHREAD
, /* Application not linked with thread library. */
58 TD_NOEVENT
, /* Requested event is not supported. */
59 TD_NOCAPAB
, /* Capability not available. */
60 TD_DBERR
, /* Internal debug library error. */
61 TD_NOAPLIC
, /* Operation is not applicable. */
62 TD_NOTSD
, /* No thread-specific data available. */
63 TD_MALLOC
, /* Out of memory. */
64 TD_PARTIALREG
, /* Not entire register set was read or written. */
65 TD_NOXREGS
, /* X register set not available for given thread. */
66 TD_NOTALLOC
/* TLS memory not yet allocated. */
70 /* Possible thread states. TD_THR_ANY_STATE is a pseudo-state used to
71 select threads regardless of state in td_ta_thr_iter(). */
84 /* Thread type: user or system. TD_THR_ANY_TYPE is a pseudo-type used
85 to select threads regardless of type in td_ta_thr_iter(). */
94 /* Types of the debugging library. */
96 /* Handle for a process. This type is opaque. */
97 typedef struct td_thragent td_thragent_t
;
99 /* The actual thread handle type. This is also opaque. */
100 typedef struct td_thrhandle
102 td_thragent_t
*th_ta_p
;
107 /* Flags for `td_ta_thr_iter'. */
108 #define TD_THR_ANY_USER_FLAGS 0xffffffff
109 #define TD_THR_LOWEST_PRIORITY -20
110 #define TD_SIGNO_MASK NULL
113 #define TD_EVENTSIZE 2
114 #define BT_UISHIFT 5 /* log base 2 of BT_NBIPUI, to
115 extract word index. */
116 #define BT_NBIPUI (1 << BT_UISHIFT) /* n bits per uint. */
117 #define BT_UIMASK (BT_NBIPUI - 1) /* to extract bit index. */
119 /* Bitmask of enabled events. */
120 typedef struct td_thr_events
122 uint32_t event_bits
[TD_EVENTSIZE
];
125 /* Event set manipulation macros. */
126 #define __td_eventmask(n) \
127 (UINT32_C (1) << (((n) - 1) & BT_UIMASK))
128 #define __td_eventword(n) \
129 ((UINT32_C ((n) - 1)) >> BT_UISHIFT)
131 #define td_event_emptyset(setp) \
134 for (__i = TD_EVENTSIZE; __i > 0; --__i) \
135 (setp)->event_bits[__i - 1] = 0; \
138 #define td_event_fillset(setp) \
141 for (__i = TD_EVENTSIZE; __i > 0; --__i) \
142 (setp)->event_bits[__i - 1] = UINT32_C (0xffffffff); \
145 #define td_event_addset(setp, n) \
146 (((setp)->event_bits[__td_eventword (n)]) |= __td_eventmask (n))
147 #define td_event_delset(setp, n) \
148 (((setp)->event_bits[__td_eventword (n)]) &= ~__td_eventmask (n))
149 #define td_eventismember(setp, n) \
150 (__td_eventmask (n) & ((setp)->event_bits[__td_eventword (n)]))
151 #if TD_EVENTSIZE == 2
152 # define td_eventisempty(setp) \
153 (!((setp)->event_bits[0]) && !((setp)->event_bits[1]))
155 # error "td_eventisempty must be changed to match TD_EVENTSIZE"
158 /* Events reportable by the thread implementation. */
161 TD_ALL_EVENTS
, /* Pseudo-event number. */
162 TD_EVENT_NONE
= TD_ALL_EVENTS
, /* Depends on context. */
163 TD_READY
, /* Is executable now. */
164 TD_SLEEP
, /* Blocked in a synchronization obj. */
165 TD_SWITCHTO
, /* Now assigned to a process. */
166 TD_SWITCHFROM
, /* Not anymore assigned to a process. */
167 TD_LOCK_TRY
, /* Trying to get an unavailable lock. */
168 TD_CATCHSIG
, /* Signal posted to the thread. */
169 TD_IDLE
, /* Process getting idle. */
170 TD_CREATE
, /* New thread created. */
171 TD_DEATH
, /* Thread terminated. */
172 TD_PREEMPT
, /* Preempted. */
173 TD_PRI_INHERIT
, /* Inherited elevated priority. */
174 TD_REAP
, /* Reaped. */
175 TD_CONCURRENCY
, /* Number of processes changing. */
176 TD_TIMEOUT
, /* Conditional variable wait timed out. */
177 TD_MIN_EVENT_NUM
= TD_READY
,
178 TD_MAX_EVENT_NUM
= TD_TIMEOUT
,
179 TD_EVENTS_ENABLE
= 31 /* Event reporting enabled. */
182 /* Values representing the different ways events are reported. */
185 NOTIFY_BPT
, /* User must insert breakpoint at
187 NOTIFY_AUTOBPT
, /* Breakpoint at u.bptaddr is automatically
189 NOTIFY_SYSCALL
/* System call u.syscallno will be invoked. */
192 /* Description how event type is reported. */
193 typedef struct td_notify
195 td_notify_e type
; /* Way the event is reported. */
198 psaddr_t bptaddr
; /* Address of breakpoint. */
199 int syscallno
; /* Number of system call used. */
203 /* Some people still have libc5 or old glibc with no uintptr_t.
204 They lose. glibc 2.1.3 was released on 2000-02-25, and it has
205 uintptr_t, so it's reasonable to force these people to upgrade. */
207 #ifndef HAVE_UINTPTR_T
208 #error No uintptr_t available; your C library is too old.
209 /* Inhibit further compilation errors after this error. */
210 #define uintptr_t void *
213 /* Structure used to report event. */
214 typedef struct td_event_msg
216 td_event_e event
; /* Event type being reported. */
217 const td_thrhandle_t
*th_p
; /* Thread reporting the event. */
221 td_synchandle_t
*sh
; /* Handle of synchronization object. */
223 uintptr_t data
; /* Event specific data. */
227 /* Structure containing event data available in each thread structure. */
230 td_thr_events_t eventmask
; /* Mask of enabled events. */
231 td_event_e eventnum
; /* Number of last event. */
232 void *eventdata
; /* Data associated with event. */
236 /* Gathered statistics about the process. */
237 typedef struct td_ta_stats
239 int nthreads
; /* Total number of threads in use. */
240 int r_concurrency
; /* Concurrency level requested by user. */
241 int nrunnable_num
; /* Average runnable threads, numerator. */
242 int nrunnable_den
; /* Average runnable threads, denominator. */
243 int a_concurrency_num
; /* Achieved concurrency level, numerator. */
244 int a_concurrency_den
; /* Achieved concurrency level, denominator. */
245 int nlwps_num
; /* Average number of processes in use,
247 int nlwps_den
; /* Average number of processes in use,
249 int nidle_num
; /* Average number of idling processes,
251 int nidle_den
; /* Average number of idling processes,
256 /* Since Sun's library is based on Solaris threads we have to define a few
257 types to map them to POSIX threads. */
258 typedef pthread_t thread_t
;
259 typedef pthread_key_t thread_key_t
;
262 /* Callback for iteration over threads. */
263 typedef int td_thr_iter_f (const td_thrhandle_t
*, void *);
265 /* Callback for iteration over thread local data. */
266 typedef int td_key_iter_f (thread_key_t
, void (*) (void *), void *);
270 /* Forward declaration. This has to be defined by the user. */
271 struct ps_prochandle
;
274 /* Information about the thread. */
275 typedef struct td_thrinfo
277 td_thragent_t
*ti_ta_p
; /* Process handle. */
278 unsigned int ti_user_flags
; /* Unused. */
279 thread_t ti_tid
; /* Thread ID returned by
281 char *ti_tls
; /* Pointer to thread-local data. */
282 psaddr_t ti_startfunc
; /* Start function passed to
284 psaddr_t ti_stkbase
; /* Base of thread's stack. */
285 long int ti_stksize
; /* Size of thread's stack. */
286 psaddr_t ti_ro_area
; /* Unused. */
287 int ti_ro_size
; /* Unused. */
288 td_thr_state_e ti_state
; /* Thread state. */
289 unsigned char ti_db_suspended
; /* Nonzero if suspended by
291 td_thr_type_e ti_type
; /* Type of the thread (system vs
293 intptr_t ti_pc
; /* Unused. */
294 intptr_t ti_sp
; /* Unused. */
295 short int ti_flags
; /* Unused. */
296 int ti_pri
; /* Thread priority. */
297 lwpid_t ti_lid
; /* Kernel pid for this thread. */
298 sigset_t ti_sigmask
; /* Signal mask. */
299 unsigned char ti_traceme
; /* Nonzero if event reporting
301 unsigned char ti_preemptflag
; /* Unused. */
302 unsigned char ti_pirecflag
; /* Unused. */
303 sigset_t ti_pending
; /* Set of pending signals. */
304 td_thr_events_t ti_events
; /* Set of enabled events. */
309 /* Prototypes for exported library functions. */
311 /* Initialize the thread debug support library. */
312 extern td_err_e
td_init (void);
314 /* Historical relict. Should not be used anymore. */
315 extern td_err_e
td_log (void);
317 /* Generate new thread debug library handle for process PS. */
318 extern td_err_e
td_ta_new (struct ps_prochandle
*__ps
, td_thragent_t
**__ta
);
320 /* Free resources allocated for TA. */
321 extern td_err_e
td_ta_delete (td_thragent_t
*__ta
);
323 /* Get number of currently running threads in process associated with TA. */
324 extern td_err_e
td_ta_get_nthreads (const td_thragent_t
*__ta
, int *__np
);
326 /* Return process handle passed in `td_ta_new' for process associated with
328 extern td_err_e
td_ta_get_ph (const td_thragent_t
*__ta
,
329 struct ps_prochandle
**__ph
);
331 /* Map thread library handle PT to thread debug library handle for process
332 associated with TA and store result in *TH. */
333 extern td_err_e
td_ta_map_id2thr (const td_thragent_t
*__ta
, pthread_t __pt
,
334 td_thrhandle_t
*__th
);
336 /* Map process ID LWPID to thread debug library handle for process
337 associated with TA and store result in *TH. */
338 extern td_err_e
td_ta_map_lwp2thr (const td_thragent_t
*__ta
, lwpid_t __lwpid
,
339 td_thrhandle_t
*__th
);
342 /* Call for each thread in a process associated with TA the callback function
344 extern td_err_e
td_ta_thr_iter (const td_thragent_t
*__ta
,
345 td_thr_iter_f
*__callback
, void *__cbdata_p
,
346 td_thr_state_e __state
, int __ti_pri
,
347 sigset_t
*__ti_sigmask_p
,
348 unsigned int __ti_user_flags
);
350 /* Call for each defined thread local data entry the callback function KI. */
351 extern td_err_e
td_ta_tsd_iter (const td_thragent_t
*__ta
, td_key_iter_f
*__ki
,
355 /* Get event address for EVENT. */
356 extern td_err_e
td_ta_event_addr (const td_thragent_t
*__ta
,
357 td_event_e __event
, td_notify_t
*__ptr
);
359 /* Enable EVENT in global mask. */
360 extern td_err_e
td_ta_set_event (const td_thragent_t
*__ta
,
361 td_thr_events_t
*__event
);
363 /* Disable EVENT in global mask. */
364 extern td_err_e
td_ta_clear_event (const td_thragent_t
*__ta
,
365 td_thr_events_t
*__event
);
367 /* Return information about last event. */
368 extern td_err_e
td_ta_event_getmsg (const td_thragent_t
*__ta
,
369 td_event_msg_t
*msg
);
372 /* Set suggested concurrency level for process associated with TA. */
373 extern td_err_e
td_ta_setconcurrency (const td_thragent_t
*__ta
, int __level
);
376 /* Enable collecting statistics for process associated with TA. */
377 extern td_err_e
td_ta_enable_stats (const td_thragent_t
*__ta
, int __enable
);
379 /* Reset statistics. */
380 extern td_err_e
td_ta_reset_stats (const td_thragent_t
*__ta
);
382 /* Retrieve statistics from process associated with TA. */
383 extern td_err_e
td_ta_get_stats (const td_thragent_t
*__ta
,
384 td_ta_stats_t
*__statsp
);
387 /* Validate that TH is a thread handle. */
388 extern td_err_e
td_thr_validate (const td_thrhandle_t
*__th
);
390 /* Return information about thread TH. */
391 extern td_err_e
td_thr_get_info (const td_thrhandle_t
*__th
,
392 td_thrinfo_t
*__infop
);
394 /* Retrieve floating-point register contents of process running thread TH. */
395 extern td_err_e
td_thr_getfpregs (const td_thrhandle_t
*__th
,
396 prfpregset_t
*__regset
);
398 /* Retrieve general register contents of process running thread TH. */
399 extern td_err_e
td_thr_getgregs (const td_thrhandle_t
*__th
,
400 prgregset_t __gregs
);
402 /* Retrieve extended register contents of process running thread TH. */
403 extern td_err_e
td_thr_getxregs (const td_thrhandle_t
*__th
, void *__xregs
);
405 /* Get size of extended register set of process running thread TH. */
406 extern td_err_e
td_thr_getxregsize (const td_thrhandle_t
*__th
, int *__sizep
);
408 /* Set floating-point register contents of process running thread TH. */
409 extern td_err_e
td_thr_setfpregs (const td_thrhandle_t
*__th
,
410 const prfpregset_t
*__fpregs
);
412 /* Set general register contents of process running thread TH. */
413 extern td_err_e
td_thr_setgregs (const td_thrhandle_t
*__th
,
414 prgregset_t __gregs
);
416 /* Set extended register contents of process running thread TH. */
417 extern td_err_e
td_thr_setxregs (const td_thrhandle_t
*__th
,
421 /* Enable reporting for EVENT for thread TH. */
422 extern td_err_e
td_thr_event_enable (const td_thrhandle_t
*__th
, int __event
);
424 /* Enable EVENT for thread TH. */
425 extern td_err_e
td_thr_set_event (const td_thrhandle_t
*__th
,
426 td_thr_events_t
*__event
);
428 /* Disable EVENT for thread TH. */
429 extern td_err_e
td_thr_clear_event (const td_thrhandle_t
*__th
,
430 td_thr_events_t
*__event
);
432 /* Get event message for thread TH. */
433 extern td_err_e
td_thr_event_getmsg (const td_thrhandle_t
*__th
,
434 td_event_msg_t
*__msg
);
437 /* Set priority of thread TH. */
438 extern td_err_e
td_thr_setprio (const td_thrhandle_t
*__th
, int __prio
);
441 /* Set pending signals for thread TH. */
442 extern td_err_e
td_thr_setsigpending (const td_thrhandle_t
*__th
,
443 unsigned char __n
, const sigset_t
*__ss
);
445 /* Set signal mask for thread TH. */
446 extern td_err_e
td_thr_sigsetmask (const td_thrhandle_t
*__th
,
447 const sigset_t
*__ss
);
450 /* Return thread local data associated with key TK in thread TH. */
451 extern td_err_e
td_thr_tsd (const td_thrhandle_t
*__th
,
452 const thread_key_t __tk
, void **__data
);
455 /* Suspend execution of thread TH. */
456 extern td_err_e
td_thr_dbsuspend (const td_thrhandle_t
*__th
);
458 /* Resume execution of thread TH. */
459 extern td_err_e
td_thr_dbresume (const td_thrhandle_t
*__th
);
461 #endif /* thread_db.h */
463 #endif /* HAVE_THREAD_DB_H */