manual/dynlink.texi

   1 @node Dynamic Linker
   2 @c @node Dynamic Linker, Internal Probes, Threads, Top
   3 @c %MENU% Loading programs and shared objects.
   4 @chapter Dynamic Linker
   5 @cindex dynamic linker
   6 @cindex dynamic loader
   7
   8 The @dfn{dynamic linker} is responsible for loading dynamically linked
   9 programs and their dependencies (in the form of shared objects).  The
  10 dynamic linker in @theglibc{} also supports loading shared objects (such
  11 as plugins) later at run time.
  12
  13 Dynamic linkers are sometimes called @dfn{dynamic loaders}.
  14
  15 @menu
  16 * Dynamic Linker Introspection::    Interfaces for querying mapping information.
  17 @end menu
  18
  19 @node Dynamic Linker Introspection
  20 @section Dynamic Linker Introspection
  21
  22 @Theglibc{} provides various functions for querying information from the
  23 dynamic linker.
  24
  25 @deftp {Data Type} {struct dl_find_object}
  26 @standards{GNU, dlfcn.h}
  27 This structure contains information about a main program or loaded
  28 object.  The @code{_dl_find_object} function uses it to return
  29 result data to the caller.
  30
  31 @table @code
  32 @item unsigned long long int dlfo_flags
  33 Currently unused and always 0.
  34
  35 @item void *dlfo_map_start
  36 The start address of the inspected mapping.  This information comes from
  37 the program header, so it follows its convention, and the address is not
  38 necessarily page-aligned.
  39
  40 @item void *dlfo_map_end
  41 The end address of the mapping.
  42
  43 @item struct link_map *dlf_link_map
  44 This member contains a pointer to the link map of the object.
  45
  46 @item struct link_map *dlf_link_map
  47 This member contains a pointer to the exception handling data of the
  48 object.  See @code{DLFO_EH_SEGMENT_TYPE} below.
  49
  50 @end table
  51
  52 This structure is a GNU extension.
  53 @end deftp
  54
  55 @deftypevr Macro int DLFO_STRUCT_HAS_EH_DBASE
  56 @standards{GNU, dlfcn.h}
  57 On most targets, this macro is defined as @code{0}.  If it is defined to
  58 @code{1}, @code{struct dl_find_object} contains an additional member
  59 @code{dlfo_eh_dbase} of type @code{void *}.  It is the base address for
  60 @code{DW_EH_PE_datarel} DWARF encodings to this location.
  61
  62 This macro is a GNU extension.
  63 @end deftypevr
  64
  65 @deftypevr Macro int DLFO_STRUCT_HAS_EH_COUNT
  66 @standards{GNU, dlfcn.h}
  67 On most targets, this macro is defined as @code{0}.  If it is defined to
  68 @code{1}, @code{struct dl_find_object} contains an additional member
  69 @code{dlfo_eh_count} of type @code{int}.  It is the number of exception
  70 handling entries in the EH frame segment identified by the
  71 @code{dlfo_eh_frame} member.
  72
  73 This macro is a GNU extension.
  74 @end deftypevr
  75
  76 @deftypevr Macro int DLFO_EH_SEGMENT_TYPE
  77 @standards{GNU, dlfcn.h}
  78 On targets using DWARF-based exception unwinding, this macro expands to
  79 @code{PT_GNU_EH_FRAME}.  This indicates that @code{dlfo_eh_frame} in
  80 @code{struct dl_find_object} points to the @code{PT_GNU_EH_FRAME}
  81 segment of the object.  On targets that use other unwinding formats, the
  82 macro expands to the program header type for the unwinding data.
  83
  84 This macro is a GNU extension.
  85 @end deftypevr
  86
  87 @deftypefun {int} _dl_find_object (void *@var{address}, struct dl_find_object *@var{result})
  88 @standards{GNU, dlfcn.h}
  89 @safety{@mtsafe{}@assafe{}@acsafe{}}
  90 On success, this function returns 0 and writes about the object
  91 surrounding the address to @code{*@var{result}}.  On failure, -1 is
  92 returned.
  93
  94 The @var{address} can be a code address or data address.  On
  95 architectures using function descriptors, no attempt is made to decode
  96 the function descriptor.  Depending on how these descriptors are
  97 implemented, @code{_dl_find_object} may return the object that defines
  98 the function descriptor (and not the object that contains the code
  99 implementing the function), or fail to find any object at all.
 100
 101 On success @var{address} is greater than or equal to
 102 @code{@var{result}->dlfo_map_start} and less than
 103 @code{@var{result}->dlfo_map_end}, that is, the supplied code address is
 104 located within the reported mapping.
 105
 106 This function returns a pointer to the unwinding information for the
 107 object that contains the program code @var{address} in
 108 @code{@var{result}->dlfo_eh_frame}.  If the platform uses DWARF
 109 unwinding information, this is the in-memory address of the
 110 @code{PT_GNU_EH_FRAME} segment.  See @code{DLFO_EH_SEGMENT_TYPE} above.
 111 In case @var{address} resides in an object that lacks unwinding information,
 112 the function still returns 0, but sets @code{@var{result}->dlfo_eh_frame}
 113 to a null pointer.
 114
 115 @code{_dl_find_object} itself is thread-safe.  However, if the
 116 application invokes @code{dlclose} for the object that contains
 117 @var{address} concurrently with @code{_dl_find_object} or after the call
 118 returns, accessing the unwinding data for that object or the link map
 119 (through @code{@var{result}->dlfo_link_map}) is not safe.  Therefore, the
 120 application needs to ensure by other means (e.g., by convention) that
 121 @var{address} remains a valid code address while the unwinding
 122 information is processed.
 123
 124 This function is a GNU extension.
 125 @end deftypefun
 126
 127
 128 @c FIXME these are undocumented:
 129 @c dladdr
 130 @c dladdr1
 131 @c dlclose
 132 @c dlerror
 133 @c dlinfo
 134 @c dlmopen
 135 @c dlopen
 136 @c dlsym
 137 @c dlvsym