rtld.h revision 2020b2b6df0384feda1732f65486c4604fbf5bea
98N/A * CDDL HEADER START 98N/A * The contents of this file are subject to the terms of the 606N/A * Common Development and Distribution License (the "License"). 98N/A * You may not use this file except in compliance with the License. 98N/A * See the License for the specific language governing permissions 98N/A * and limitations under the License. 98N/A * When distributing Covered Code, include this CDDL HEADER in each 98N/A * If applicable, add the following below this CDDL HEADER, with the 98N/A * fields enclosed by brackets "[]" replaced with your own identifying 98N/A * information: Portions Copyright [yyyy] [name of copyright owner] 98N/A * Copyright (c) 1995, 2010, Oracle and/or its affiliates. All rights reserved. 98N/A * Global include file for the runtime linker. 98N/A * We use rtld_ino_t instead of ino_t so that we can get 98N/A * access to large inode values from 32-bit code. 493N/A * A binding descriptor. Establishes the binding relationship between two 493N/A * objects, the caller (originator) and the dependency (destination). 235N/A * Every relationship between two objects is tracked by a binding descriptor. 235N/A * This descriptor is referenced from a link-map's DEPENDS and CALLERS lists. 493N/A * Note, Aplist's are diagramed to fully expose the allocations required to 493N/A * establish the data structure relationships. 98N/A * ------------| b_caller | 98N/A * | | b_depend | ---------- 606N/A * Rt_map | ---------- | Rt_map 591N/A * ---------- | ^ ^ | ---------- 587N/A * | DEPENDS | ----> | | | | -------- | | 587N/A * | | | | | | | | <---- | CALLERS | 606N/A * | | | | --- | | | | | 493N/A * ---------- Aplist -------- ---------- 591N/A /* for diagnostics only */ 591N/A * Private structure for communication between rtld_db and rtld. 591N/A * We must bump the version number when ever an update in one of the 98N/A * rtld_db implementations of the future to recognize core files produced on 98N/A * older systems and deal with these core files accordingly. 98N/A * As of version 'R_RTLDDB_VERSION <= 2' the following fields were valid for 98N/A * core file examination (basically the public Link_map): 111N/A * Valid fields for R_RTLDDB_VERSION3 98N/A * Valid fields for R_RTLDDB_VERSION4 622N/A * Valid fields for R_RTLDDB_VERSION5 622N/A * Added rtld_flags & FLG_RT_RELOCED to stable flags range 212N/A * Valid fields for R_RTLDDB_VERSION6 606N/A * rtd_dynlmlst converted from a List to APlist * External function definitions. ld.so.1 must convey information to libc in * regards to threading. libc also provides routines for atexit() and message * localization. libc provides the necessary interfaces via its RTLDINFO * structure and/or later _ld_libc() calls. * These external functions are maintained for each link-map list, and used * where appropriate. The functions are associated with the object that * provided them, so that should the object be deleted (say, from an alternative * link-map), the functions can be removed. int (*
lc_func)();
/* external function pointer */ char *
lc_ptr;
/* external character pointer */ * Link map list definition. Link-maps are used to describe each loaded object. * Lists of these link-maps describe the various namespaces within a process. * The process executable and its dependencies are maintained on the lml_main * list. The runtime linker, and its dependencies are maintained on the * lml_rtld list. Additional lists can be created (see dlmopen()) for such * things as auditors and their dependencies. * Each link-map list maintains an Alist of one, or more, linked lists of * link-maps. For backward compatibility, the lm_head/lm_tail elements are * initialized to the first linked-list of link-maps: * | lm_tail | ------------------------------------ * | lm_head | -------------------- | * | | Alist --> | | |--> | | * | | --------- | | | -- | | * | lm_lists | ----> | | | | | --> | | * | | |---------| | | | | | | * | | | lc_head | -- ------ | ------ * | | | lc_tail | ------------------ * Multiple link-map lists exist to support the addition of lazy loaded * families, filtee families, and dlopen() families. The intent of these * lists is to insure that a family of objects that are to be loaded are * fully relocatable, and hence usable, before they become part of the main * (al_data[0]) link-map control list. This main link-map control list is * the only list in existence when control is transferred to user code. * During process initialization, the dynamic executable and its non-lazy * dependencies are maintained on al_data[0]. If a new object is loaded, then * this object is added to the next available control list [1], typically * al_data[1]. Any dependencies of this object that have not already been * loaded are added to the same control list. Once all of the objects on the * new control list have been successfully relocated, the objects are moved from * the new control list to the highest control list to which objects of the new * control list bound to, typically al_data[1] to al_data[0]. * Each loading scenario can be broken down as follows: * setup() - only the initial link-map control list is used: * ii. add new link-map for main on al_data[0] * iii. analyze al_data[0] to add all non-lazy dependencies * iv. relocate al_data[0] dependencies. * dlopen() - the initiator can only be the initial link-map control list: * i. create al_data[1] from caller al_data[0] * ii. add new link-map for the dlopen'ed object on al_data[1] * iii. analyze al_data[1] to add all non-lazy dependencies * iv. relocate al_data[1] dependencies, and move to al_data[0]. * filtee and lazy loading processing - the initiator can be any link-map * control list that is being relocated: * i. create al_data[y] from caller al_data[x] * ii. add new link-map for the new object on al_data[y] * iii. analyze al_data[y] to add all non-lazy dependencies * iv. relocate al_data[y] dependencies, and move to al_data[x]. * This Alist therefore maintains a stack of link-map control lists. The newest * link-map control list can locate symbols within any of the former lists, * however, control is not passed to a former list until the newest lists * processing is complete. Thus, objects can't bind to new objects until they * have been fully analyzed and relocated. * [1] Note, additional link-map control list creation occurs after the head * link-map object (typically the dynamic executable) has been relocated. This * staging is required to satisfy the binding requirements of copy relocations. * Copy relocations, effectively, transfer the bindings of the copied data * (say _iob in libc.so.1) to the copy location (_iob in the application). * Thus an object that might bind to the original copy data must be redirected * to the copy reference. As the knowledge of a copy relocation having taken * place is only known after relocating the application, link-map control list * additions are suspended until after this relocation has completed. /* interposers are added */ * BEGIN: Exposed to rtld_db - don't move, don't delete /* is required for flags */ * END: Exposed to rtld_db - don't move, don't delete char ***
lm_environ;
/* pointer to environment array */ char *
lm_lmidstr;
/* and associated diagnostic string */ * BEGIN: Exposed to rtld_db - don't move, don't delete * END: Exposed to rtld_db - don't move, don't delete * Possible Link_map list flags (Lm_list.lm_flags) * BEGIN: Exposed to rtld_db - don't move, don't delete * END: Exposed to rtld_db - don't move, don't delete /* initialization (ld.so.1 */ /* internal for crle(1) */ * Possible Link_map transferable flags (Lm_list.lm_tflags), i.e., link-map * list flags that can be propagated to any new link-map list created. * NOTE: Each auditing module establishes a set of audit flags, AFLAGS(), that * define the auditing interfaces the module offers. These auditing flags are * the LML_TFLG_AUD_ flags defined above. Global auditors result in setting * the lm_tflags too. Local auditors only use the AFLAGS(). All tests for * auditing inspect the lm_tflags and AFLAGS() for a specific auditing * interface, and thus use the same flag to test for both types of auditors. * The capability of ld.so.1 to associate a group of objects, look for symbols * within that group, ensure that groups are isolated from one another (with * regard to relocations), and to unload a group, centers around a handle. * Dependencies can be added to an existing handle as the dependencies are * lazily loaded. The core dependencies on the handle are the ldd(1) list of * Handles can be created from: * - a dlopen() request. This associates a caller to a reference object, * and the referenced objects dependencies. This group of objects can * then be inspected for symbols (dlsym()). * - a filtering request. This associates a filter (caller) to a referenced * object (filtee). The redirection of filter symbols to their filtee * counterpart is essentially a dlsym() using the filtee's handle. * The handle created for these events is referred to as a public handle. This * handle tracks the referenced object, all of the dependencies of the * referenced object, and the caller (parent). * Presently, an object may have two handles, one requested with RTLD_FIRST * A handle may be referenced by any number of callers (parents). A reference * count tracks the number. A dlclose() operation drops the reference count, * and when the count is zero, the handle is used to determine the family of * objects to unload. As bindings may occur to objects on the handle from * other handles, it may not be possible to remove a complete family of objects * or the handle itself. Handles in this state are moved to an orphan list. * A handle on the orphan list is taken off the orphan list if the associated * object is reopened. Otherwise, the handle remains on the orphan list for * the duration of the process. The orphan list is inspected any time objects * are unloaded, to determine if the orphaned objects can also be unloaded. * Handles can also be created for internal uses: * - to promote objects to RTLD_NOW. * - to establish families for symbol binding fallback, required when lazy * loadable objects are still pending. * The handle created for these events is referred to as a private handle. This * handle does not need to track the caller (parent), and because of this, does * not need to be considered during dlclose() operations, as the handle can not * be referenced by callers outside of the referenced objects family. * Note, a private handle is essentially a subset of a public handle. Should * an internal operation require a private handle, and a public handle already * exist, the public handle can be used. Should an external operation require * a public handle, and a private handle exist, the private handle is promoted * to a public handle. Any handle that gets created will remain in existence * for the life time of the referenced object. * Objects can be dlopened using RTLD_NOW. This attribute requires that all * relocations of the object, and its dependencies are processed immediately, * before return to the caller. Typically, an object is loaded without * RTLD_NOW, and procedure linkage relocations are satisfied when their * associated function is first called. If an object is already loaded, and an * RTLD_NOW request is made, then the object, and its dependencies, most undergo * additional relocation processing. This promotion from lazy binding to * immediate binding is carried out using handles, as the handle defines the * dependencies that must be processed. * To ensure that objects within a lazy loadable environment can be relocated, * no matter whether the objects have their dependencies described completely, * a symbol lookup fallback is employed. Any pending lazy loadable objects are * loaded, and a handle established to search the object and it's dependencies * for the required symbol. * A group handle (and its associated group descriptors), is referenced from * a link-map's HANDLES and GROUPS lists. Note, Aplist's are diagramed to * fully expose the allocations required to establish the data structure * | | gd_depend | --------- * --------|--- | gd_depend | | * | --------- | gh_ownlmp | | * Rt_map | | ------------ | Rt_map * ---------- | | ^ ^ | ---------- * | | <--- -------- | | | | * | HANDLES | ----> | | | | -------- | | * | | | | | | | | <---- | GROUPS | * ---------- Aplist -------- ---------- * Define the two categories of handle. #
define GPH_PUBLIC 0x0001 /* handle returned to caller(s) */#
define GPH_PRIVATE 0x0002 /* handle used internally */ * Define any flags that affects how the handle is used. #
define GPH_ZERO 0x0010 /* special handle for dlopen(0) */#
define GPH_FIRST 0x0040 /* dlsym() can only use originating */#
define GPH_FILTEE 0x0080 /* handle identifies a filtee, used */ /* for diagnostics only */ * Define any state that is associated with the handle. * Define a Group Descriptor. * Each dependency associated with a group handle is maintained by a group * descriptor. The descriptor defines the associated dependency together with * flags that indicate how the dependency can be used. #
define GPD_DLSYM 0x0001 /* dependency available to dlsym() */#
define GPD_RELOC 0x0002 /* dependency available to satisfy */#
define GPD_ADDEPS 0x0004 /* dependencies of this dependency */ /* should be added to handle */ #
define GPD_PARENT 0x0008 /* dependency is a parent */#
define GPD_FILTER 0x0010 /* dependency is our filter */#
define GPD_REMOVE 0x0100 /* descriptor is a candidate for */ /* removal from the group */ * Define threading structures. For compatibility with libthread (T1_VERSION 1 * and TI_VERSION 2) our locking structure is sufficient to hold a mutex or a * Define a dynamic section information descriptor. This parallels the entries * in the .dynamic section and holds auxiliary information to implement lazy * loading and filtee processing. /* and DT_SYMAUXILIARY */ #
define MSK_DI_FILTER 0x0000f /* mask for all filter possibilities */#
define FLG_DI_IGNORE 0x00080 /* .dynamic entry should be ignored */#
define FLG_DI_LAZY 0x00100 /* lazy needed entry, preceded by */ /* DF_P1_LAZYLOAD (DT_POSFLAG_1) */ #
define FLG_DI_GROUP 0x00200 /* group needed entry, preceded by */ /* DF_P1_GROUPPERM (DT_POSFLAG_1) */ /* DF_P1_DEFERRED (DT_POSFLAG_1) */ * Data structure to track AVL tree of pathnames. This structure provides the * basis of both the "not-found" node tree, and the "full-path" node tree. Both * of these trees persist for the life of a process, although the "not-found" * tree may be moved aside during a dlopen() or dlsym() fall back operation. const char *
pn_name;
/* path name */ * Data structure to track AVL tree for full path names of objects that are * A given link-map can hold either a supplier or receiver copy * relocation list, but not both. This union is used to overlap * the space used for the two lists. * BEGIN: Exposed to rtld_db - don't move, don't delete const char *
rt_pathname;
/* full pathname of loaded object */ * END: Exposed to rtld_db - don't move, don't delete char *
rt_runpath;
/* LD_RUN_PATH and its equivalent */ struct fct *
rt_fct;
/* file class table for this object */ void *
rt_priv;
/* private data, object type specific */ int rt_mode;
/* usage mode, see RTLD mode flags */ int rt_sortval;
/* temporary buffer to traverse graph */ const char *
rt_origname;
/* original pathname of loaded object */ /* because it is checked in */ /* link map symbol interpreter */ * Structure to allow 64-bit rtld_db to read 32-bit processes out of procfs. * BEGIN: Exposed to rtld_db - don't move, don't delete * END: Exposed to rtld_db - don't move, don't delete * BEGIN: Exposed to rtld_db - don't move, don't delete #
define FLG_RT_ISMAIN 0x00000001 /* object represents main executable */ * Available for r_debug version >= R_RTLDDB_VERSION5 * END: Exposed to rtld_db - don't move, don't delete #
define FLG_RT_CAP 0x00000010 /* process $CAPABILITY expansion */#
define FLG_RT_OBJECT 0x00000020 /* object processing (ie. .o's) */#
define FLG_RT_NODUMP 0x00000080 /* object can't be dldump(3x)'ed */#
define FLG_RT_TRANS 0x00000800 /* object is acting as a translator */#
define FLG_RT_FIXED 0x00001000 /* image location is fixed */#
define FLG_RT_ALTER 0x00004000 /* alternative object used */#
define FLG_RT_MOVE 0x02000000 /* object needs move operation */#
define FLG_RT_REGSYMS 0x08000000 /* object has DT_REGISTER entries */#
define FLG_RT_PUBHDL 0x20000000 /* generate a handle for this object */#
define FL1_RT_ALTCAP 0x00000004 /* alternative system capabilities */#
define FL1_RT_USED 0x00000400 /* symbol referenced from this object */ /* symbolic sym resolution */ #
define MSK_RT_FILTER 0x0000f000 /* mask for all filter possibilities */#
define FL1_RT_TLSADD 0x00010000 /* objects TLS has been registered */#
define FL1_RT_DIRECT 0x00040000 /* object has DIRECT bindings enabled */ * Flags for the tls_modactivity() routine * Macros for getting to exposed, link_map data (R_RTLDDB_VERSION <= 2). * An Rt_map starts with a Link_map, followed by other information. * ld.so.1 allocates Rt_map structures, and then casts them to Link_map, * and back, depending on context. * On some platforms, Rt_map can have a higher alignment requirement * than Link_map. On such platforms, the cast from Link_map to Rt_map will * draw an E_BAD_PTR_CAST_ALIGN warning from lint. Since we allocate * the memory as the higher alignment Rt_map, we know that this is a safe * conversion. The LINKMAP_TO_RTMAP macro is used to handle the conversion * in a manner that satisfies lint. * Convenience macros for the common case of using * NEXT()/PREV() and casting the result to (Rt_map *) * Macros for getting to exposed, link_map data (R_RTLDDB_VERSION3). * Macros for getting to exposed, link_map data (R_RTLDDB_VERSION4). * Macros for getting to unexposed, link-map data. #
define RT_SORT_FWD 0x01 /* topological sort (.fini) */#
define RT_SORT_REV 0x02 /* reverse topological sort (.init) */ /* only (called via dlclose()) */ * Flags for lookup_sym (and hence find_sym) routines. #
define LKUP_DEFT 0x0000 /* simple lookup request */#
define LKUP_SPEC 0x0001 /* special ELF lookup (allows address */ /* resolutions to plt[] entries) */ #
define LKUP_LDOT 0x0002 /* indicates the original A_OUT */ /* symbol had a leading `.' */ #
define LKUP_FIRST 0x0004 /* lookup symbol in first link map */#
define LKUP_COPY 0x0008 /* lookup symbol for a COPY reloc, do */ /* not bind to symbol at head */ #
define LKUP_STDRELOC 0x0010 /* lookup originates from a standard */ /* relocation (elf_reloc()) */ #
define LKUP_SELF 0x0020 /* lookup symbol in ourself - undef */#
define LKUP_WEAK 0x0040 /* relocation reference is weak */#
define LKUP_NEXT 0x0080 /* request originates from RTLD_NEXT */#
define LKUP_NODESCENT 0x0100 /* don't descend through dependencies */ /* pending lazy dependencies */ #
define LKUP_DIRECT 0x0400 /* direct binding request */#
define LKUP_SYMNDX 0x0800 /* establish symbol index */#
define LKUP_STANDARD 0x2000 /* standard lookup - originated from */ /* head link-map element */ #
define LKUP_WORLD 0x4000 /* ensure world lookup */#
define LKUP_DLSYM 0x8000 /* lookup stems from dlsym() request */ * For the runtime linker to perform a symbol search, a number of data items * related to the search are required. An Slookup data structure is used to * convey this data to lookup_sym(), and in special cases, to other core * routines that provide the implementation details for lookup_sym() * The symbol name (sl_name), the caller (sl_cmap), and the link-map from which * to start the search (sl_imap) are fundamental to the symbol search. The * initial search link-map might get modified by the core routines that provide * the implementation details for lookup_sym(). This modification accommodates * requirements such as processing a handle, direct binding and interposition. * The association between the caller and the potential destination also * determines whether the destination is a candidate to search. * The lookup identifier (sl_id) is used to identify a runtime linker operation. * Within this operation, any lazy loads that fail are not re-examined. This * technique keeps the overhead of processing a failed lazy load to a minimum. * Symbol searches that originate from a relocation record are accompanied by * the relocation index (sl_rsymndx), the symbol reference (sl_rsym) and * possibly the relocation type (sl_rtype). This data provides for determining * lazy loading, direct binding, and special symbol processing requirements * such as copy relocations and singleton lookup. * The symbols hash value is computed by lookup_sym, and propagated throughout * the search engine. Note, occasionally the Slookup data is passed to a core * routine that provides the implementation details for lookup_sym(), ie. * elf_find_sym(), in which case the caller must initialize the hash value. * The symbols binding information is established by lookup_sym() when the * symbols relocation type is supplied. Weak bindings allow relocations to * be set to zero should a symbol lookup fail. * The flags allow the caller to control aspects of the search, including the * interpretation of copy relocations, etc. Note, a number of flag settings * are established in lookup_sym() from attributes of the symbol reference. const char *
sl_name;
/* symbol name */ * After a symbol lookup has been resolved, the runtime linker needs to retain * information regarding the bound definition. An Sresult data structure is * used to provide this information. * The symbol name (sr_name) may differ from the original referenced symbol if * a symbol capabilities family member has resolved the binding. The defining * object (sr_dmap) indicates the object in which the definition has been found. * The symbol table entry (sr_sym) defines the bound symbol definition. * Note, a symbol lookup may start with one Sresult buffer, but underlying * routines (for example, those that probe filters) might employ their own * Sresult buffer. If a binding is allowed, the latter buffer may get inherited * by the former. Along with this chain of requests, binding info (binfo) and * not-found information (in_nfavl), may be passed between all the associated * functions. Hence, the binfo and in_nfavl data is not maintained as part of const char *
sr_name;
/* symbol definition name */ * Define a system capabilities structure for maintaining the various * capabilities of the system. This structure follows the Objcapset definition * from libld.h, however the system can only have one platform or machine * hardware name, thus this structure is a little simpler. char *
sc_plat;
/* CA_SUNW_PLAT capability */ char *
sc_mach;
/* CA_SUNW_MACH capability */ * Define a number of .plt lookup outcomes, for use in binding diagnostics.