Back to index

glibc  2.9
thread_db.h
Go to the documentation of this file.
00001 /* thread_db.h -- interface to libthread_db.so library for debugging -lpthread
00002    Copyright (C) 1999,2001,2002,2003 Free Software Foundation, Inc.
00003    This file is part of the GNU C Library.
00004 
00005    The GNU C Library is free software; you can redistribute it and/or
00006    modify it under the terms of the GNU Lesser General Public
00007    License as published by the Free Software Foundation; either
00008    version 2.1 of the License, or (at your option) any later version.
00009 
00010    The GNU C Library is distributed in the hope that it will be useful,
00011    but WITHOUT ANY WARRANTY; without even the implied warranty of
00012    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00013    Lesser General Public License for more details.
00014 
00015    You should have received a copy of the GNU Lesser General Public
00016    License along with the GNU C Library; if not, write to the Free
00017    Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
00018    02111-1307 USA.  */
00019 
00020 #ifndef _THREAD_DB_H
00021 #define _THREAD_DB_H 1
00022 
00023 /* This is the debugger interface for the LinuxThreads library.  It is
00024    modelled closely after the interface with same names in Solaris with
00025    the goal to share the same code in the debugger.  */
00026 #include <pthread.h>
00027 #include <stdint.h>
00028 #include <sys/types.h>
00029 #include <sys/procfs.h>
00030 
00031 
00032 /* Error codes of the library.  */
00033 typedef enum
00034 {
00035   TD_OK,        /* No error.  */
00036   TD_ERR,       /* No further specified error.  */
00037   TD_NOTHR,     /* No matching thread found.  */
00038   TD_NOSV,      /* No matching synchronization handle found.  */
00039   TD_NOLWP,     /* No matching light-weighted process found.  */
00040   TD_BADPH,     /* Invalid process handle.  */
00041   TD_BADTH,     /* Invalid thread handle.  */
00042   TD_BADSH,     /* Invalid synchronization handle.  */
00043   TD_BADTA,     /* Invalid thread agent.  */
00044   TD_BADKEY,    /* Invalid key.  */
00045   TD_NOMSG,     /* No event available.  */
00046   TD_NOFPREGS,         /* No floating-point register content available.  */
00047   TD_NOLIBTHREAD, /* Application not linked with thread library.  */
00048   TD_NOEVENT,   /* Requested event is not supported.  */
00049   TD_NOCAPAB,   /* Capability not available.  */
00050   TD_DBERR,     /* Internal debug library error.  */
00051   TD_NOAPLIC,   /* Operation is not applicable.  */
00052   TD_NOTSD,     /* No thread-specific data available.  */
00053   TD_MALLOC,    /* Out of memory.  */
00054   TD_PARTIALREG,  /* Not entire register set was read or written.  */
00055   TD_NOXREGS,   /* X register set not available for given thread.  */
00056   TD_TLSDEFER,         /* Thread has not yet allocated TLS for given module.  */
00057   TD_NOTALLOC = TD_TLSDEFER,
00058   TD_VERSION,   /* Version if libpthread and libthread_db do not match.  */
00059   TD_NOTLS      /* There is TLS segment in the given module.  */
00060 } td_err_e;
00061 
00062 
00063 /* Possible thread states.  TD_THR_ANY_STATE is a pseudo-state used to
00064    select threads regardless of state in td_ta_thr_iter().  */
00065 typedef enum
00066 {
00067   TD_THR_ANY_STATE,
00068   TD_THR_UNKNOWN,
00069   TD_THR_STOPPED,
00070   TD_THR_RUN,
00071   TD_THR_ACTIVE,
00072   TD_THR_ZOMBIE,
00073   TD_THR_SLEEP,
00074   TD_THR_STOPPED_ASLEEP
00075 } td_thr_state_e;
00076 
00077 /* Thread type: user or system.  TD_THR_ANY_TYPE is a pseudo-type used
00078    to select threads regardless of type in td_ta_thr_iter().  */
00079 typedef enum
00080 {
00081   TD_THR_ANY_TYPE,
00082   TD_THR_USER,
00083   TD_THR_SYSTEM
00084 } td_thr_type_e;
00085 
00086 
00087 /* Types of the debugging library.  */
00088 
00089 /* Handle for a process.  This type is opaque.  */
00090 typedef struct td_thragent td_thragent_t;
00091 
00092 /* The actual thread handle type.  This is also opaque.  */
00093 typedef struct td_thrhandle
00094 {
00095   td_thragent_t *th_ta_p;
00096   psaddr_t th_unique;
00097 } td_thrhandle_t;
00098 
00099 
00100 /* Forward declaration of a type defined by and for the dynamic linker.  */
00101 struct link_map;
00102 
00103 
00104 /* Flags for `td_ta_thr_iter'.  */
00105 #define TD_THR_ANY_USER_FLAGS      0xffffffff
00106 #define TD_THR_LOWEST_PRIORITY     -20
00107 #define TD_SIGNO_MASK              NULL
00108 
00109 
00110 #define TD_EVENTSIZE 2
00111 #define BT_UISHIFT   5 /* log base 2 of BT_NBIPUI, to extract word index */
00112 #define BT_NBIPUI    (1 << BT_UISHIFT)       /* n bits per uint */
00113 #define BT_UIMASK    (BT_NBIPUI - 1)         /* to extract bit index */
00114 
00115 /* Bitmask of enabled events. */
00116 typedef struct td_thr_events
00117 {
00118   uint32_t event_bits[TD_EVENTSIZE];
00119 } td_thr_events_t;
00120 
00121 /* Event set manipulation macros. */
00122 #define __td_eventmask(n) \
00123   (UINT32_C (1) << (((n) - 1) & BT_UIMASK))
00124 #define __td_eventword(n) \
00125   ((UINT32_C ((n) - 1)) >> BT_UISHIFT)
00126 
00127 #define td_event_emptyset(setp) \
00128   do {                                                               \
00129     int __i;                                                         \
00130     for (__i = TD_EVENTSIZE; __i > 0; --__i)                                \
00131       (setp)->event_bits[__i - 1] = 0;                                      \
00132   } while (0)
00133 
00134 #define td_event_fillset(setp) \
00135   do {                                                               \
00136     int __i;                                                         \
00137     for (__i = TD_EVENTSIZE; __i > 0; --__i)                                \
00138       (setp)->event_bits[__i - 1] = UINT32_C (0xffffffff);                  \
00139   } while (0)
00140 
00141 #define td_event_addset(setp, n) \
00142   (((setp)->event_bits[__td_eventword (n)]) |= __td_eventmask (n))
00143 #define td_event_delset(setp, n) \
00144   (((setp)->event_bits[__td_eventword (n)]) &= ~__td_eventmask (n))
00145 #define td_eventismember(setp, n) \
00146   (__td_eventmask (n) & ((setp)->event_bits[__td_eventword (n)]))
00147 #if TD_EVENTSIZE == 2
00148 # define td_eventisempty(setp) \
00149   (!((setp)->event_bits[0]) && !((setp)->event_bits[1]))
00150 #else
00151 # error "td_eventisempty must be changed to match TD_EVENTSIZE"
00152 #endif
00153 
00154 /* Events reportable by the thread implementation.  */
00155 typedef enum
00156 {
00157   TD_ALL_EVENTS,             /* Pseudo-event number.  */
00158   TD_EVENT_NONE = TD_ALL_EVENTS, /* Depends on context.  */
00159   TD_READY,                  /* Is executable now. */
00160   TD_SLEEP,                  /* Blocked in a synchronization obj.  */
00161   TD_SWITCHTO,                      /* Now assigned to a process.  */
00162   TD_SWITCHFROM,             /* Not anymore assigned to a process.  */
00163   TD_LOCK_TRY,                      /* Trying to get an unavailable lock.  */
00164   TD_CATCHSIG,                      /* Signal posted to the thread.  */
00165   TD_IDLE,                   /* Process getting idle.  */
00166   TD_CREATE,                 /* New thread created.  */
00167   TD_DEATH,                  /* Thread terminated.  */
00168   TD_PREEMPT,                /* Preempted.  */
00169   TD_PRI_INHERIT,            /* Inherited elevated priority.  */
00170   TD_REAP,                   /* Reaped.  */
00171   TD_CONCURRENCY,            /* Number of processes changing.  */
00172   TD_TIMEOUT,                /* Conditional variable wait timed out.  */
00173   TD_MIN_EVENT_NUM = TD_READY,
00174   TD_MAX_EVENT_NUM = TD_TIMEOUT,
00175   TD_EVENTS_ENABLE = 31            /* Event reporting enabled.  */
00176 } td_event_e;
00177 
00178 /* Values representing the different ways events are reported.  */
00179 typedef enum
00180 {
00181   NOTIFY_BPT,               /* User must insert breakpoint at u.bptaddr. */
00182   NOTIFY_AUTOBPT,           /* Breakpoint at u.bptaddr is automatically
00183                                inserted.  */
00184   NOTIFY_SYSCALL            /* System call u.syscallno will be invoked.  */
00185 } td_notify_e;
00186 
00187 /* Description how event type is reported.  */
00188 typedef struct td_notify
00189 {
00190   td_notify_e type;         /* Way the event is reported.  */
00191   union
00192   {
00193     psaddr_t bptaddr;              /* Address of breakpoint.  */
00194     int syscallno;          /* Number of system call used.  */
00195   } u;
00196 } td_notify_t;
00197 
00198 /* Structure used to report event.  */
00199 typedef struct td_event_msg
00200 {
00201   td_event_e event;         /* Event type being reported.  */
00202   const td_thrhandle_t *th_p;      /* Thread reporting the event.  */
00203   union
00204   {
00205 # if 0
00206     td_synchandle_t *sh;    /* Handle of synchronization object.  */
00207 #endif
00208     uintptr_t data;         /* Event specific data.  */
00209   } msg;
00210 } td_event_msg_t;
00211 
00212 /* Structure containing event data available in each thread structure.  */
00213 typedef struct
00214 {
00215   td_thr_events_t eventmask;       /* Mask of enabled events.  */
00216   td_event_e eventnum;             /* Number of last event.  */
00217   void *eventdata;          /* Data associated with event.  */
00218 } td_eventbuf_t;
00219 
00220 
00221 /* Gathered statistics about the process.  */
00222 typedef struct td_ta_stats
00223 {
00224   int nthreads;                    /* Total number of threads in use.  */
00225   int r_concurrency;        /* Concurrency level requested by user.  */
00226   int nrunnable_num;        /* Average runnable threads, numerator.  */
00227   int nrunnable_den;        /* Average runnable threads, denominator.  */
00228   int a_concurrency_num;    /* Achieved concurrency level, numerator.  */
00229   int a_concurrency_den;    /* Achieved concurrency level, denominator.  */
00230   int nlwps_num;            /* Average number of processes in use,
00231                                numerator.  */
00232   int nlwps_den;            /* Average number of processes in use,
00233                                denominator.  */
00234   int nidle_num;            /* Average number of idling processes,
00235                                numerator.  */
00236   int nidle_den;            /* Average number of idling processes,
00237                                denominator.  */
00238 } td_ta_stats_t;
00239 
00240 
00241 /* Since Sun's library is based on Solaris threads we have to define a few
00242    types to map them to POSIX threads.  */
00243 typedef pthread_t thread_t;
00244 typedef pthread_key_t thread_key_t;
00245 
00246 
00247 /* Callback for iteration over threads.  */
00248 typedef int td_thr_iter_f (const td_thrhandle_t *, void *);
00249 
00250 /* Callback for iteration over thread local data.  */
00251 typedef int td_key_iter_f (thread_key_t, void (*) (void *), void *);
00252 
00253 
00254 
00255 /* Forward declaration.  This has to be defined by the user.  */
00256 struct ps_prochandle;
00257 
00258 
00259 /* Information about the thread.  */
00260 typedef struct td_thrinfo
00261 {
00262   td_thragent_t *ti_ta_p;          /* Process handle.  */
00263   unsigned int ti_user_flags;             /* Unused.  */
00264   thread_t ti_tid;                 /* Thread ID returned by
00265                                       pthread_create().  */
00266   char *ti_tls;                           /* Pointer to thread-local data.  */
00267   psaddr_t ti_startfunc;           /* Start function passed to
00268                                       pthread_create().  */
00269   psaddr_t ti_stkbase;                    /* Base of thread's stack.  */
00270   long int ti_stksize;                    /* Size of thread's stack.  */
00271   psaddr_t ti_ro_area;                    /* Unused.  */
00272   int ti_ro_size;                  /* Unused.  */
00273   td_thr_state_e ti_state;         /* Thread state.  */
00274   unsigned char ti_db_suspended;   /* Nonzero if suspended by debugger. */
00275   td_thr_type_e ti_type;           /* Type of the thread (system vs
00276                                       user thread).  */
00277   intptr_t ti_pc;                  /* Unused.  */
00278   intptr_t ti_sp;                  /* Unused.  */
00279   short int ti_flags;                     /* Unused.  */
00280   int ti_pri;                      /* Thread priority.  */
00281   lwpid_t ti_lid;                  /* Unused.  */
00282   sigset_t ti_sigmask;                    /* Signal mask.  */
00283   unsigned char ti_traceme;        /* Nonzero if event reporting
00284                                       enabled.  */
00285   unsigned char ti_preemptflag;           /* Unused.  */
00286   unsigned char ti_pirecflag;             /* Unused.  */
00287   sigset_t ti_pending;                    /* Set of pending signals.  */
00288   td_thr_events_t ti_events;              /* Set of enabled events.  */
00289 } td_thrinfo_t;
00290 
00291 
00292 
00293 /* Prototypes for exported library functions.  */
00294 
00295 /* Initialize the thread debug support library.  */
00296 extern td_err_e td_init (void);
00297 
00298 /* Historical relict.  Should not be used anymore.  */
00299 extern td_err_e td_log (void);
00300 
00301 /* Return list of symbols the library can request.  */
00302 extern const char **td_symbol_list (void);
00303 
00304 /* Generate new thread debug library handle for process PS.  */
00305 extern td_err_e td_ta_new (struct ps_prochandle *__ps, td_thragent_t **__ta);
00306 
00307 /* Free resources allocated for TA.  */
00308 extern td_err_e td_ta_delete (td_thragent_t *__ta);
00309 
00310 /* Get number of currently running threads in process associated with TA.  */
00311 extern td_err_e td_ta_get_nthreads (const td_thragent_t *__ta, int *__np);
00312 
00313 /* Return process handle passed in `td_ta_new' for process associated with
00314    TA.  */
00315 extern td_err_e td_ta_get_ph (const td_thragent_t *__ta,
00316                            struct ps_prochandle **__ph);
00317 
00318 /* Map thread library handle PT to thread debug library handle for process
00319    associated with TA and store result in *TH.  */
00320 extern td_err_e td_ta_map_id2thr (const td_thragent_t *__ta, pthread_t __pt,
00321                               td_thrhandle_t *__th);
00322 
00323 /* Map process ID LWPID to thread debug library handle for process
00324    associated with TA and store result in *TH.  */
00325 extern td_err_e td_ta_map_lwp2thr (const td_thragent_t *__ta, lwpid_t __lwpid,
00326                                td_thrhandle_t *__th);
00327 
00328 
00329 /* Call for each thread in a process associated with TA the callback function
00330    CALLBACK.  */
00331 extern td_err_e td_ta_thr_iter (const td_thragent_t *__ta,
00332                             td_thr_iter_f *__callback, void *__cbdata_p,
00333                             td_thr_state_e __state, int __ti_pri,
00334                             sigset_t *__ti_sigmask_p,
00335                             unsigned int __ti_user_flags);
00336 
00337 /* Call for each defined thread local data entry the callback function KI.  */
00338 extern td_err_e td_ta_tsd_iter (const td_thragent_t *__ta, td_key_iter_f *__ki,
00339                             void *__p);
00340 
00341 
00342 /* Get event address for EVENT.  */
00343 extern td_err_e td_ta_event_addr (const td_thragent_t *__ta,
00344                               td_event_e __event, td_notify_t *__ptr);
00345 
00346 /* Enable EVENT in global mask.  */
00347 extern td_err_e td_ta_set_event (const td_thragent_t *__ta,
00348                              td_thr_events_t *__event);
00349 
00350 /* Disable EVENT in global mask.  */
00351 extern td_err_e td_ta_clear_event (const td_thragent_t *__ta,
00352                                td_thr_events_t *__event);
00353 
00354 /* Return information about last event.  */
00355 extern td_err_e td_ta_event_getmsg (const td_thragent_t *__ta,
00356                                 td_event_msg_t *__msg);
00357 
00358 
00359 /* Set suggested concurrency level for process associated with TA.  */
00360 extern td_err_e td_ta_setconcurrency (const td_thragent_t *__ta, int __level);
00361 
00362 
00363 /* Enable collecting statistics for process associated with TA.  */
00364 extern td_err_e td_ta_enable_stats (const td_thragent_t *__ta, int __enable);
00365 
00366 /* Reset statistics.  */
00367 extern td_err_e td_ta_reset_stats (const td_thragent_t *__ta);
00368 
00369 /* Retrieve statistics from process associated with TA.  */
00370 extern td_err_e td_ta_get_stats (const td_thragent_t *__ta,
00371                              td_ta_stats_t *__statsp);
00372 
00373 
00374 /* Validate that TH is a thread handle.  */
00375 extern td_err_e td_thr_validate (const td_thrhandle_t *__th);
00376 
00377 /* Return information about thread TH.  */
00378 extern td_err_e td_thr_get_info (const td_thrhandle_t *__th,
00379                              td_thrinfo_t *__infop);
00380 
00381 /* Retrieve floating-point register contents of process running thread TH.  */
00382 extern td_err_e td_thr_getfpregs (const td_thrhandle_t *__th,
00383                               prfpregset_t *__regset);
00384 
00385 /* Retrieve general register contents of process running thread TH.  */
00386 extern td_err_e td_thr_getgregs (const td_thrhandle_t *__th,
00387                              prgregset_t __gregs);
00388 
00389 /* Retrieve extended register contents of process running thread TH.  */
00390 extern td_err_e td_thr_getxregs (const td_thrhandle_t *__th, void *__xregs);
00391 
00392 /* Get size of extended register set of process running thread TH.  */
00393 extern td_err_e td_thr_getxregsize (const td_thrhandle_t *__th, int *__sizep);
00394 
00395 /* Set floating-point register contents of process running thread TH.  */
00396 extern td_err_e td_thr_setfpregs (const td_thrhandle_t *__th,
00397                               const prfpregset_t *__fpregs);
00398 
00399 /* Set general register contents of process running thread TH.  */
00400 extern td_err_e td_thr_setgregs (const td_thrhandle_t *__th,
00401                              prgregset_t __gregs);
00402 
00403 /* Set extended register contents of process running thread TH.  */
00404 extern td_err_e td_thr_setxregs (const td_thrhandle_t *__th,
00405                              const void *__addr);
00406 
00407 
00408 /* Get address of the given module's TLS storage area for the given thread.  */
00409 extern td_err_e td_thr_tlsbase (const td_thrhandle_t *__th,
00410                             unsigned long int __modid,
00411                             psaddr_t *__base);
00412 
00413 /* Get address of thread local variable.  */
00414 extern td_err_e td_thr_tls_get_addr (const td_thrhandle_t *__th,
00415                                  void *__map_address, size_t __offset,
00416                                  void **__address);
00417 
00418 
00419 /* Enable reporting for EVENT for thread TH.  */
00420 extern td_err_e td_thr_event_enable (const td_thrhandle_t *__th, int __event);
00421 
00422 /* Enable EVENT for thread TH.  */
00423 extern td_err_e td_thr_set_event (const td_thrhandle_t *__th,
00424                               td_thr_events_t *__event);
00425 
00426 /* Disable EVENT for thread TH.  */
00427 extern td_err_e td_thr_clear_event (const td_thrhandle_t *__th,
00428                                 td_thr_events_t *__event);
00429 
00430 /* Get event message for thread TH.  */
00431 extern td_err_e td_thr_event_getmsg (const td_thrhandle_t *__th,
00432                                  td_event_msg_t *__msg);
00433 
00434 
00435 /* Set priority of thread TH.  */
00436 extern td_err_e td_thr_setprio (const td_thrhandle_t *__th, int __prio);
00437 
00438 
00439 /* Set pending signals for thread TH.  */
00440 extern td_err_e td_thr_setsigpending (const td_thrhandle_t *__th,
00441                                   unsigned char __n, const sigset_t *__ss);
00442 
00443 /* Set signal mask for thread TH.  */
00444 extern td_err_e td_thr_sigsetmask (const td_thrhandle_t *__th,
00445                                const sigset_t *__ss);
00446 
00447 
00448 /* Return thread local data associated with key TK in thread TH.  */
00449 extern td_err_e td_thr_tsd (const td_thrhandle_t *__th,
00450                          const thread_key_t __tk, void **__data);
00451 
00452 
00453 /* Suspend execution of thread TH.  */
00454 extern td_err_e td_thr_dbsuspend (const td_thrhandle_t *__th);
00455 
00456 /* Resume execution of thread TH.  */
00457 extern td_err_e td_thr_dbresume (const td_thrhandle_t *__th);
00458 
00459 #endif /* thread_db.h */