master
1/* thread_db.h -- interface to libthread_db.so library for debugging -lpthread
2 Copyright (C) 1999-2025 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 <https://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. */
32typedef 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. */
56 TD_NOTALLOC = TD_TLSDEFER,
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(). */
64typedef enum
65{
66 TD_THR_ANY_STATE,
67 TD_THR_UNKNOWN,
68 TD_THR_STOPPED,
69 TD_THR_RUN,
70 TD_THR_ACTIVE,
71 TD_THR_ZOMBIE,
72 TD_THR_SLEEP,
73 TD_THR_STOPPED_ASLEEP
74} td_thr_state_e;
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(). */
78typedef enum
79{
80 TD_THR_ANY_TYPE,
81 TD_THR_USER,
82 TD_THR_SYSTEM
83} td_thr_type_e;
84
85
86/* Types of the debugging library. */
87
88/* Handle for a process. This type is opaque. */
89typedef struct td_thragent td_thragent_t;
90
91/* The actual thread handle type. This is also opaque. */
92typedef struct td_thrhandle
93{
94 td_thragent_t *th_ta_p;
95 psaddr_t th_unique;
96} td_thrhandle_t;
97
98
99/* Forward declaration of a type defined by and for the dynamic linker. */
100struct 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 unsigned int */
112#define BT_UIMASK (BT_NBIPUI - 1) /* to extract bit index */
113
114/* Bitmask of enabled events. */
115typedef struct td_thr_events
116{
117 uint32_t event_bits[TD_EVENTSIZE];
118} td_thr_events_t;
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. */
154typedef 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. */
172 TD_MIN_EVENT_NUM = TD_READY,
173 TD_MAX_EVENT_NUM = TD_TIMEOUT,
174 TD_EVENTS_ENABLE = 31 /* Event reporting enabled. */
175} td_event_e;
176
177/* Values representing the different ways events are reported. */
178typedef 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. */
187typedef 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. */
198typedef 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;
209} td_event_msg_t;
210
211/* Structure containing event data available in each thread structure. */
212typedef 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. */
221typedef 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. */
242typedef pthread_t thread_t;
243typedef pthread_key_t thread_key_t;
244
245
246/* Callback for iteration over threads. */
247typedef int td_thr_iter_f (const td_thrhandle_t *, void *);
248
249/* Callback for iteration over thread local data. */
250typedef 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. */
255struct ps_prochandle;
256
257
258/* Information about the thread. */
259typedef 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. */
295extern td_err_e td_init (void);
296
297/* Historical relict. Should not be used anymore. */
298extern td_err_e td_log (void);
299
300/* Return list of symbols the library can request. */
301extern const char **td_symbol_list (void);
302
303/* Generate new thread debug library handle for process PS. */
304extern td_err_e td_ta_new (struct ps_prochandle *__ps, td_thragent_t **__ta);
305
306/* Free resources allocated for TA. */
307extern td_err_e td_ta_delete (td_thragent_t *__ta);
308
309/* Get number of currently running threads in process associated with TA. */
310extern 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. */
314extern 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. */
319extern 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. */
324extern 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. */
330extern 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. */
337extern 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. */
342extern 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. */
346extern 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. */
350extern 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. */
354extern 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. */
359extern td_err_e td_ta_setconcurrency (const td_thragent_t *__ta, int __level);
360
361
362/* Enable collecting statistics for process associated with TA. */
363extern td_err_e td_ta_enable_stats (const td_thragent_t *__ta, int __enable);
364
365/* Reset statistics. */
366extern td_err_e td_ta_reset_stats (const td_thragent_t *__ta);
367
368/* Retrieve statistics from process associated with TA. */
369extern 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. */
374extern td_err_e td_thr_validate (const td_thrhandle_t *__th);
375
376/* Return information about thread TH. */
377extern 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. */
381extern 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. */
385extern 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. */
389extern 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. */
392extern 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. */
395extern 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. */
399extern 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. */
403extern 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. */
408extern 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. */
413extern 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. */
419extern td_err_e td_thr_event_enable (const td_thrhandle_t *__th, int __event);
420
421/* Enable EVENT for thread TH. */
422extern 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. */
426extern 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. */
430extern 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. */
435extern td_err_e td_thr_setprio (const td_thrhandle_t *__th, int __prio);
436
437
438/* Set pending signals for thread TH. */
439extern 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. */
443extern 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. */
448extern 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. */
453extern td_err_e td_thr_dbsuspend (const td_thrhandle_t *__th);
454
455/* Resume execution of thread TH. */
456extern td_err_e td_thr_dbresume (const td_thrhandle_t *__th);
457
458#endif /* thread_db.h */