elf/rtld-debugger-interface.txt

   1 Standard debugger interface
   2 ===========================
   3
   4 The run-time linker exposes a rendezvous structure to allow debuggers
   5 to interface with it.  This structure, r_debug, is defined in link.h.
   6 If the executable's dynamic section has a DT_DEBUG element, the
   7 run-time linker sets that element's value to the address where this
   8 structure can be found.
   9
  10 The r_debug structure contains (amongst others) the following fields:
  11
  12   int r_version:
  13     Version number for this protocol.  It should be greater than 0.
  14
  15   struct link_map *r_map:
  16     A linked list of loaded objects.
  17
  18   enum { RT_CONSISTENT, RT_ADD, RT_DELETE } r_state:
  19     The current state of the r_map list.  RT_CONSISTENT means that r_map
  20     is not currently being modified and may safely be inspected.  RT_ADD
  21     means that an object is being added to r_map, and that the list is
  22     not guaranteed to be consistent.  Likewise RT_DELETE means that an
  23     object is being removed from the list.
  24
  25   ElfW(Addr) r_brk:
  26     The address of a function internal to the run-time linker which is
  27     called whenever r_state is changed.  The debugger should set a
  28     breakpoint at this address if it wants to notice mapping changes.
  29
  30 This protocol is widely supported, but somewhat limited in that it
  31 has no provision to provide access to multiple namespaces, and that
  32 the notifications (via r_brk) only refer to changes to r_map--the
  33 debugger is notified that a new object has been added, for instance,
  34 but there is no way for the debugger to discover whether any of the
  35 objects in the link-map have been relocated or not.
  36
  37
  38 Extension to the r_debug structure
  39 ==================================
  40
  41 The r_debug_extended structure is an extension of the r_debug interface.
  42 If r_version is 2, one additional field is available:
  43
  44   struct r_debug_extended *r_next;
  45     Link to the next r_debug_extended structure.  Each r_debug_extended
  46     structure represents a different namespace.  A namespace is active
  47     if its r_map field isn't NULL.  The first r_debug_extended structure
  48     is for the default namespace.
  49
  50 Probe-based debugger interface
  51 ==============================
  52
  53 Systemtap is a dynamic tracing/instrumenting tool available on Linux.
  54 Probes that are not fired at run time have close to zero overhead.
  55 glibc contains a number of probes that debuggers can set breakpoints
  56 on in order to notice certain events.
  57
  58 All rtld probes have the following arguments:
  59
  60   arg1: Lmid_t lmid:
  61     The link-map ID of the link-map list that the object was loaded
  62     into.  This will be LM_ID_BASE for the application's main link-map
  63     list, or some other value for different namespaces.
  64
  65   arg2: struct r_debug *r_debug:
  66     A pointer to the r_debug structure containing the link-map list
  67     that the object was loaded into.  This will be the value stored in
  68     DT_DEBUG for the application's main link-map list, or some other
  69     value for different namespaces.
  70
  71 map_complete and reloc_complete may have the following additional
  72 argument:
  73
  74   arg3: struct link_map *new:
  75     A pointer which, if not NULL, points to the entry in the specified
  76     r_debug structure's link-map list corresponding to the first new
  77     object to have been mapped or relocated, with new->l_next pointing
  78     to the link-map of the next new object to have been mapped or
  79     relocated, and so on.  Note that because `new' is an entry in a
  80     larger list, new->l_prev (if not NULL) will point to what was the
  81     last link-map in the link-map list prior to the new objects being
  82     mapped or relocated.
  83
  84 The following probes are available:
  85
  86   init_start:
  87     This is called once, when the linker is about to fill in the main
  88     r_debug structure at application startup.  init_start always has
  89     lmid set to LM_ID_BASE and r_debug set to the value stored in
  90     DT_DEBUG.  r_debug is not guaranteed to be consistent until
  91     init_complete is fired.
  92
  93   init_complete:
  94     This is called once, when the linker has filled in the main
  95     r_debug structure at application startup. init_complete always
  96     has lmid set to LM_ID_BASE and r_debug set to the value stored
  97     in DT_DEBUG.  The r_debug structure is consistent and may be
  98     inspected, and all objects in the link-map are guaranteed to
  99     have been relocated.
 100
 101   map_start:
 102     The linker is about to map new objects into the specified
 103     namespace.  The namespace's r_debug structure is not guaranteed
 104     to be consistent until a corresponding map_complete is fired.
 105
 106   map_complete:
 107     The linker has finished mapping new objects into the specified
 108     namespace.  The namespace's r_debug structure is consistent and
 109     may be inspected, although objects in the namespace's link-map
 110     are not guaranteed to have been relocated.
 111
 112   map_failed:
 113     The linker failed while attempting to map new objects into
 114     the specified namespace.  The namespace's r_debug structure
 115     is consistent and may be inspected.
 116
 117   reloc_start:
 118     The linker is about to relocate all unrelocated objects in the
 119     specified namespace.  The namespace's r_debug structure is not
 120     guaranteed to be consistent until a corresponding reloc_complete
 121     is fired.
 122
 123   reloc_complete:
 124     The linker has relocated all objects in the specified namespace.
 125     The namespace's r_debug structure is consistent and may be
 126     inspected, and all objects in the namespace's link-map are
 127     guaranteed to have been relocated.
 128
 129   unmap_start:
 130     The linker is about to remove objects from the specified
 131     namespace.  The namespace's r_debug structure is not guaranteed to
 132     be consistent until a corresponding unmap_complete is fired.
 133
 134   unmap_complete:
 135     The linker has finished removing objects into the specified
 136     namespace.  The namespace's r_debug structure is consistent and
 137     may be inspected.