elf/link.h

   1 /* Run-time dynamic linker data structures for loaded ELF shared objects.
   2    Copyright (C) 1995, 1996, 1997 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 Library General Public License as
   7    published by the Free Software Foundation; either version 2 of the
   8    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    Library General Public License for more details.
  14
  15    You should have received a copy of the GNU Library General Public
  16    License along with the GNU C Library; see the file COPYING.LIB.  If not,
  17    write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18    Boston, MA 02111-1307, USA.  */
  19
  20 #ifndef _LINK_H
  21
  22 #define _LINK_H 1
  23 #include <features.h>
  24
  25 #define __need_size_t
  26 #define __need_NULL
  27 #include <stddef.h>
  28
  29 #include <elf.h>
  30
  31 __BEGIN_DECLS
  32
  33 /* We use this macro to refer to ELF types independent of the native wordsize.
  34    `ElfW(TYPE)' is used in place of `Elf32_TYPE' or `Elf64_TYPE'.  */
  35 #define ElfW(type)      _ElfW (Elf, __ELF_NATIVE_CLASS, type)
  36 #define ELFW(type)      _ElfW (ELF, __ELF_NATIVE_CLASS, type)
  37 #define _ElfW(e,w,t)    _ElfW_1 (e, w, _##t)
  38 #define _ElfW_1(e,w,t)  e##w##t
  39 #include <elfclass.h>           /* Defines __ELF_NATIVE_CLASS.  */
  40
  41 /* Rendezvous structure used by the run-time dynamic linker to communicate
  42    details of shared object loading to the debugger.  If the executable's
  43    dynamic section has a DT_DEBUG element, the run-time linker sets that
  44    element's value to the address where this structure can be found.  */
  45
  46 struct r_debug
  47   {
  48     int r_version;              /* Version number for this protocol.  */
  49
  50     struct link_map *r_map;     /* Head of the chain of loaded objects.  */
  51
  52     /* This is the address of a function internal to the run-time linker,
  53        that will always be called when the linker begins to map in a
  54        library or unmap it, and again when the mapping change is complete.
  55        The debugger can set a breakpoint at this address if it wants to
  56        notice shared object mapping changes.  */
  57     ElfW(Addr) r_brk;
  58     enum
  59       {
  60         /* This state value describes the mapping change taking place when
  61            the `r_brk' address is called.  */
  62         RT_CONSISTENT,          /* Mapping change is complete.  */
  63         RT_ADD,                 /* Beginning to add a new object.  */
  64         RT_DELETE,              /* Beginning to remove an object mapping.  */
  65       } r_state;
  66
  67     ElfW(Addr) r_ldbase;        /* Base address the linker is loaded at.  */
  68   };
  69
  70 /* This is the instance of that structure used by the dynamic linker.  */
  71 extern struct r_debug _r_debug;
  72
  73 /* This symbol refers to the "dynamic structure" in the `.dynamic' section
  74    of whatever module refers to `_DYNAMIC'.  So, to find its own
  75    `struct r_debug', a program could do:
  76      for (dyn = _DYNAMIC; dyn->d_tag != DT_NULL)
  77        if (dyn->d_tag == DT_DEBUG) r_debug = (struct r_debug) dyn->d_un.d_ptr;
  78    */
  79
  80 extern ElfW(Dyn) _DYNAMIC[];
  81
  82 /* For the version handling we need an array with only names and their
  83    hash values.  */
  84 struct r_found_version
  85   {
  86     const char *name;
  87     ElfW(Word) hash;
  88
  89     const char *filename;
  90   };
  91
  92 /* Structure describing a loaded shared object.  The `l_next' and `l_prev'
  93    members form a chain of all the shared objects loaded at startup.
  94
  95    These data structures exist in space used by the run-time dynamic linker;
  96    modifying them may have disastrous results.  */
  97
  98 struct link_map
  99   {
 100     /* These first few members are part of the protocol with the debugger.
 101        This is the same format used in SVR4.  */
 102
 103     ElfW(Addr) l_addr;          /* Base address shared object is loaded at.  */
 104     char *l_name;               /* Absolute file name object was found in.  */
 105     ElfW(Dyn) *l_ld;            /* Dynamic section of the shared object.  */
 106     struct link_map *l_next, *l_prev; /* Chain of loaded objects.  */
 107
 108     /* All following members are internal to the dynamic linker.
 109        They may change without notice.  */
 110
 111     struct libname_list
 112       {
 113         const char *name;       /* Name requested (before search).  */
 114         struct libname_list *next; /* Link to next name for this object.  */
 115       } *l_libname;
 116     /* Indexed pointers to dynamic section.
 117        [0,DT_NUM) are indexed by the processor-independent tags.
 118        [DT_NUM,DT_NUM+DT_PROCNUM) are indexed by the tag minus DT_LOPROC.
 119        [DT_NUM+DT_PROCNUM,DT_NUM+DT_PROCNUM+DT_EXTRANUM) are indexed
 120        by DT_EXTRATAGIDX(tagvalue) and
 121        [DT_NUM+DT_PROCNUM+DT_VERSIONTAGNUM,
 122         DT_NUM+DT_PROCNUM+DT_VERSIONTAGNUM+DT_EXTRANUM)
 123        are indexed by DT_EXTRATAGIDX(tagvalue) (see <elf.h>).  */
 124
 125     ElfW(Dyn) *l_info[DT_NUM + DT_PROCNUM + DT_VERSIONTAGNUM + DT_EXTRANUM];
 126     const ElfW(Phdr) *l_phdr;   /* Pointer to program header table in core.  */
 127     ElfW(Addr) l_entry;         /* Entry point location.  */
 128     ElfW(Half) l_phnum;         /* Number of program header entries.  */
 129
 130     /* Array of DT_NEEDED dependencies and their dependencies, in
 131        dependency order for symbol lookup.  This is null before the
 132        dependencies have been loaded.  */
 133     struct link_map **l_searchlist;
 134     unsigned int l_nsearchlist;
 135
 136     /* We keep another list in which we keep duplicates.  This is
 137        needed in _dl_lookup_symbol_skip to implemented RTLD_NEXT.  */
 138     struct link_map **l_dupsearchlist;
 139     unsigned int l_ndupsearchlist;
 140
 141     /* Dependent object that first caused this object to be loaded.  */
 142     struct link_map *l_loader;
 143
 144     /* Symbol hash table.  */
 145     ElfW(Symndx) l_nbuckets;
 146     const ElfW(Symndx) *l_buckets, *l_chain;
 147
 148     unsigned int l_opencount;   /* Reference count for dlopen/dlclose.  */
 149     enum                        /* Where this object came from.  */
 150       {
 151         lt_executable,          /* The main executable program.  */
 152         lt_library,             /* Library needed by main executable.  */
 153         lt_loaded,              /* Extra run-time loaded shared object.  */
 154       } l_type:2;
 155     unsigned int l_relocated:1; /* Nonzero if object's relocations done.  */
 156     unsigned int l_init_called:1; /* Nonzero if DT_INIT function called.  */
 157     unsigned int l_init_running:1; /* Nonzero while DT_INIT function runs.  */
 158     unsigned int l_global:1;    /* Nonzero if object in _dl_global_scope.  */
 159     unsigned int l_reserved:2;  /* Reserved for internal use.  */
 160
 161     /* Array with version names.  */
 162     unsigned int l_nversions;
 163     struct r_found_version *l_versions;
 164   };
 165
 166
 167 /* Test whether given NAME matches any of the names of the given object.  */
 168 static inline int
 169 __attribute__ ((unused))
 170 _dl_name_match_p (const char *__name, struct link_map *__map)
 171 {
 172   int __found = strcmp (__name, __map->l_name) == 0;
 173   struct libname_list *__runp = __map->l_libname;
 174
 175   while (! __found && __runp != NULL)
 176     if (strcmp (__name, __runp->name) == 0)
 177       __found = 1;
 178     else
 179       __runp = __runp->next;
 180
 181   return __found;
 182 }
 183
 184 /* Function used as argument for `_dl_receive_error' function.  The
 185    arguments are the error code, error string, and the objname the
 186    error occurred in.  */
 187 typedef void (*receiver_fct) (int, const char *, const char *);
 188 \f
 189 /* Internal functions of the run-time dynamic linker.
 190    These can be accessed if you link again the dynamic linker
 191    as a shared library, as in `-lld' or `/lib/ld.so' explicitly;
 192    but are not normally of interest to user programs.
 193
 194    The `-ldl' library functions in <dlfcn.h> provide a simple
 195    user interface to run-time dynamic linking.  */
 196
 197
 198 /* Cached value of `getpagesize ()'.  */
 199 extern size_t _dl_pagesize;
 200
 201 /* File descriptor referring to the zero-fill device.  */
 202 extern int _dl_zerofd;
 203
 204 /* OS-dependent function to open the zero-fill device.  */
 205 extern int _dl_sysdep_open_zero_fill (void); /* dl-sysdep.c */
 206
 207 /* OS-dependent function to write a message on the standard output.
 208    All arguments are `const char *'; args until a null pointer
 209    are concatenated to form the message to print.  */
 210 extern void _dl_sysdep_message (const char *string, ...);
 211
 212 /* OS-dependent function to write a message on the standard error.
 213    All arguments are `const char *'; args until a null pointer
 214    are concatenated to form the message to print.  */
 215 extern void _dl_sysdep_error (const char *string, ...);
 216
 217 /* OS-dependent function to give a fatal error message and exit
 218    when the dynamic linker fails before the program is fully linked.
 219    All arguments are `const char *'; args until a null pointer
 220    are concatenated to form the message to print.  */
 221 extern void _dl_sysdep_fatal (const char *string, ...)
 222      __attribute__ ((__noreturn__));
 223
 224 /* Nonzero if the program should be "secure" (i.e. it's setuid or somesuch).
 225    This tells the dynamic linker to ignore environment variables.  */
 226 extern int _dl_secure;
 227
 228 /* This function is called by all the internal dynamic linker functions
 229    when they encounter an error.  ERRCODE is either an `errno' code or
 230    zero; OBJECT is the name of the problematical shared object, or null if
 231    it is a general problem; ERRSTRING is a string describing the specific
 232    problem.  */
 233 extern void _dl_signal_error (int errcode,
 234                               const char *object,
 235                               const char *errstring);
 236
 237 /* Call OPERATE, catching errors from `dl_signal_error'.  If there is no
 238    error, *ERRSTRING is set to null.  If there is an error, *ERRSTRING and
 239    *OBJECT are set to the strings passed to _dl_signal_error, and the error
 240    code passed is the return value.  ERRSTRING if nonzero points to a
 241    malloc'ed string which the caller has to free after use.
 242    ARGS is passed as argument to OPERATE.  */
 243 extern int _dl_catch_error (char **errstring,
 244                             const char **object,
 245                             void (*operate) (void *),
 246                             void *args);
 247
 248 /* Call OPERATE, receiving errors from `dl_signal_error'.  Unlike
 249    `_dl_catch_error' the operation is resumed after the OPERATE
 250    function returns.
 251    ARGS is passed as argument to OPERATE.  */
 252 extern void _dl_receive_error (receiver_fct fct, void (*operate) (void *),
 253                                void *args);
 254
 255
 256 /* Helper function for <dlfcn.h> functions.  Runs the OPERATE function via
 257    _dl_catch_error.  Returns zero for success, nonzero for failure; and
 258    arranges for `dlerror' to return the error details.
 259    ARGS is passed as argument to OPERATE.  */
 260 extern int _dlerror_run (void (*operate) (void *), void *args);
 261
 262
 263 /* Open the shared object NAME and map in its segments.
 264    LOADER's DT_RPATH is used in searching for NAME.
 265    If the object is already opened, returns its existing map.  */
 266 extern struct link_map *_dl_map_object (struct link_map *loader,
 267                                         const char *name, int type,
 268                                         int trace_mode);
 269
 270 /* Call _dl_map_object on the dependencies of MAP, and set up
 271    MAP->l_searchlist.  PRELOADS points to a vector of NPRELOADS previously
 272    loaded objects that will be inserted into MAP->l_searchlist after MAP
 273    but before its dependencies.  */
 274 extern void _dl_map_object_deps (struct link_map *map,
 275                                  struct link_map **preloads,
 276                                  unsigned int npreloads, int trace_mode);
 277
 278 /* Cache the locations of MAP's hash table.  */
 279 extern void _dl_setup_hash (struct link_map *map);
 280
 281
 282 /* Open the shared object NAME, relocate it, and run its initializer if it
 283    hasn't already been run.  MODE is as for `dlopen' (see <dlfcn.h>).  If
 284    the object is already opened, returns its existing map.  */
 285 extern struct link_map *_dl_open (const char *name, int mode);
 286
 287 /* Close an object previously opened by _dl_open.  */
 288 extern void _dl_close (struct link_map *map);
 289
 290
 291 /* Search loaded objects' symbol tables for a definition of the symbol
 292    referred to by UNDEF.  *SYM is the symbol table entry containing the
 293    reference; it is replaced with the defining symbol, and the base load
 294    address of the defining object is returned.  SYMBOL_SCOPE is a
 295    null-terminated list of object scopes to search; each object's
 296    l_searchlist (i.e. the segment of the dependency tree starting at that
 297    object) is searched in turn.  REFERENCE_NAME should name the object
 298    containing the reference; it is used in error messages.
 299    RELOC_TYPE is a machine-dependent reloc type, which is passed to
 300    the `elf_machine_lookup_*_p' macros in dl-machine.h to affect which
 301    symbols can be chosen.  */
 302 extern ElfW(Addr) _dl_lookup_symbol (const char *undef,
 303                                      const ElfW(Sym) **sym,
 304                                      struct link_map *symbol_scope[],
 305                                      const char *reference_name,
 306                                      int reloc_type);
 307
 308 /* Lookup versioned symbol.  */
 309 extern ElfW(Addr) _dl_lookup_versioned_symbol (const char *undef,
 310                                                const ElfW(Sym) **sym,
 311                                                struct link_map *symbol_scope[],
 312                                                const char *reference_name,
 313                                                const struct r_found_version *version,
 314                                                int reloc_type);
 315
 316 /* For handling RTLD_NEXT we must be able to skip shared objects.  */
 317 extern ElfW(Addr) _dl_lookup_symbol_skip (const char *undef,
 318                                           const ElfW(Sym) **sym,
 319                                           struct link_map *symbol_scope[],
 320                                           const char *reference_name,
 321                                           struct link_map *skip_this);
 322
 323 /* For handling RTLD_NEXT with versioned symbols we must be able to
 324    skip shared objects.  */
 325 extern ElfW(Addr) _dl_lookup_versioned_symbol_skip (const char *undef,
 326                                                     const ElfW(Sym) **sym,
 327                                                     struct link_map *symbol_scope[],
 328                                                     const char *reference_name,
 329                                                     const struct r_found_version *version,
 330                                                     struct link_map *skip_this);
 331
 332 /* Look up symbol NAME in MAP's scope and return its run-time address.  */
 333 extern ElfW(Addr) _dl_symbol_value (struct link_map *map, const char *name);
 334
 335
 336 /* Structure describing the dynamic linker itself.  */
 337 extern struct link_map _dl_rtld_map;
 338
 339 /* The list of objects currently loaded is the third element of the
 340    `_dl_default_scope' array, and the fourth element is always null.
 341    This leaves two slots before it that are used when resolving
 342    DT_SYMBOLIC objects' references one after it for normal references
 343    (see below).  */
 344 #define _dl_loaded      (_dl_default_scope[2])
 345 extern struct link_map *_dl_default_scope[5];
 346
 347 /* Null-terminated list of objects in the dynamic `global scope'.  The
 348    list starts at [2]; i.e. &_dl_global_scope[2] is the argument
 349    passed to _dl_lookup_symbol to search the global scope.  To search
 350    a specific object and its dependencies in preference to the global
 351    scope, fill in the [1] slot and pass its address; for two specific
 352    object scopes, fill [0] and [1].  The list is double-terminated; to
 353    search the global scope and then a specific object and its
 354    dependencies, set *_dl_global_scope_end.  This variable initially
 355    points to _dl_default_scope, and _dl_loaded is always kept in [2]
 356    of this list.  A new list is malloc'd when new objects are loaded
 357    with RTLD_GLOBAL.  */
 358 extern struct link_map **_dl_global_scope, **_dl_global_scope_end;
 359 extern size_t _dl_global_scope_alloc; /* Number of slots malloc'd.  */
 360
 361 /* Hack _dl_global_scope[0] and [1] as necessary, and return a pointer into
 362    _dl_global_scope that should be passed to _dl_lookup_symbol for symbol
 363    references made in the object MAP's relocations.  */
 364 extern struct link_map **_dl_object_relocation_scope (struct link_map *map);
 365
 366
 367 /* Allocate a `struct link_map' for a new object being loaded,
 368    and enter it into the _dl_loaded list.  */
 369 extern struct link_map *_dl_new_object (char *realname, const char *libname,
 370                                         int type);
 371
 372 /* Relocate the given object (if it hasn't already been).
 373    SCOPE is passed to _dl_lookup_symbol in symbol lookups.
 374    If LAZY is nonzero, don't relocate its PLT.  */
 375 extern void _dl_relocate_object (struct link_map *map,
 376                                  struct link_map *scope[],
 377                                  int lazy);
 378
 379 /* Check the version dependencies of all objects available through
 380    MAP.  If VERBOSE print some more diagnostics.  */
 381 extern int _dl_check_all_versions (struct link_map *map, int verbose);
 382
 383 /* Check the version dependencies for MAP.  If VERBOSE print some more
 384    diagnostics.  */
 385 extern int _dl_check_map_versions (struct link_map *map, int verbose);
 386
 387 /* Return the address of the next initializer function for MAP or one of
 388    its dependencies that has not yet been run.  When there are no more
 389    initializers to be run, this returns zero.  The functions are returned
 390    in the order they should be called.  */
 391 extern ElfW(Addr) _dl_init_next (struct link_map *map);
 392
 393 /* Call the finalizer functions of all shared objects whose
 394    initializer functions have completed.  */
 395 extern void _dl_fini (void);
 396
 397 /* The dynamic linker calls this function before and having changing
 398    any shared object mappings.  The `r_state' member of `struct r_debug'
 399    says what change is taking place.  This function's address is
 400    the value of the `r_brk' member.  */
 401 extern void _dl_debug_state (void);
 402
 403 /* Initialize `struct r_debug' if it has not already been done.  The
 404    argument is the run-time load address of the dynamic linker, to be put
 405    in the `r_ldbase' member.  Returns the address of the structure.  */
 406 extern struct r_debug *_dl_debug_initialize (ElfW(Addr) ldbase);
 407
 408 __END_DECLS
 409
 410 #endif /* link.h */