*** UNIX MANUAL PAGE BROWSER ***

loader(5) File Formats Manual loader(5) NAME loader - Run-time linker and loader. DESCRIPTION The loader is the run-time linker and shared object loader. You invoke loader when you run a dynamic executable. The loader maps in the main object and any shared libraries used by it, resolves relocations as ld does at static link time, and allocates common space in memory if re- quired. The loader is also referred to as rld, and some of the inter- nal interfaces currently reflect this naming. The loader constructs an explicit shared object list from the list of objects comprised by the executable. You can override the dynamic exe- cutable's list at run time by defining the _RLD_LIST environment vari- able to be a colon-separated list of objects and libraries. To append new objects to the dynamic executable's list, specify the keyword DE- FAULT at the beginning of the new object list; to prepend new objects, specify DEFAULT at the end of the new list. To add new objects to the middle of the dynamic executable's list, you must explicitly enter the full object list when defining _RLD_LIST. The default shared library search paths include: /usr/shlib /usr/ccs/lib /usr/lib/cmplrs/cc /usr/lib /usr/local/lib /var/shlib You can change and add to the shared library search paths by any of the following mechanisms: Using the -soname option to the ld command when creating a shared object. The ld command records shared library dependencies using shared object names (sonames). By default, an object's soname is its file name (without a prepended path name). The -soname option allows you to specify an alternative soname. If the soname you specify contains a path name, the shared object loader searches for it only in the indicated location, exactly as specified. If the soname contains a file name, the shared object loader con- structs a search path for the object from the file name as de- scribed below. Using the -rpath option to the ld command. The -rpath option causes the linker to associate a list of shared library search directories (separated by colons) with a call shared or shared object. If an item in the path supplied to -rpath is of the form $VARNAME or ${VARNAME}, the loader in- terprets it as an environment variable. Defining the _RLD_ROOT environment variable. The _RLD_ROOT environment variable defines a list of root direc- tory paths (separated by colons) that are, in turn, prepended to each directory specified in the main executable's rpath and to the default shared library search paths. The _RLD_ROOT environ- ment variable does not, by itself, identify a list of directo- ries to be searched. To search the system default library di- rectories when _RLD_ROOT is defined, you must include the true root directory (/) as one of its entries. Defining the LD_LI- BRARY_PATH environment variable. The LD_LIBRARY_PATH environment variable defines a list of shared library directories that are always searched as speci- fied. The shared object loader does not prepend to these direc- tories the root directory path prefixes defined by the _RLD_ROOT environment variable. If an item in the list defined by the LD_LIBRARY_PATH environment variable is of the form $VARNAME or ${VARNAME}, the loader interprets it as an environment variable. As mentioned above, if the object's soname contains a path name, the shared object loader searches for it only in the indicated location, exactly as specified. If the soname contains a file name, the shared object loader constructs its search path for shared objects in the fol- lowing manner: The list of shared library search directories indicated by the rpath of the main executable, each prepended by any root paths defined by the _RLD_ROOT environment variable Any list of shared li- brary search directories defined by the LD_LIBRARY_PATH environment variable The default shared library search paths, each prepended by any root paths defined by the _RLD_ROOT environment variable To ensure compatibility, applications may choose to disallow exec-time or run-time library replacement. The ld(1) program supports a flag, -no_library_replacement, to facilitate this feature. Security also dictates that the loader will not allow library replace- ment for setuid and setgid programs unless the user is root. Loader Entry Points The loader is invoked on the initial exec and is reentered via lazy_text_resolve. This function implements lazy binding by resolving text symbols on the fly at run time. The symbol __istart is bound to a handler for L.init sections, and is called by crt0. Before exiting, programs or objects should call _rld_new_interface(_SHUT_DOWN) to en- sure that the program executes all of the sections for all of the shared objects. The crt0 and exit(2) library routines call _rld_new_interface(_SHUT_DOWN), so that programs linked using cc(1) will have standard handling of and L.fini sections. Programmers are encouraged to use the higher level entry points dlopen(3), dlsym(3), dlclose(3), and dlerror(3) to perform run-time li- brary loading and symbol resolution. The following facilities avail- able through _rld_new_interface are evolving and should not be used by portable programs. #include <rld_interface.h> void *_rld_new_interface(Elf32_Word operation, ...) This function returns different types of objects depending on the oper- ation code, so casting is required as indicated below. The following operation codes implement some basic functionalities that are super- seded for the most part by dlopen(3), etc.: /* Run fini routines */ (int)_rld_new_interface(_SHUT_DOWN) /* Return first path name in object list */ (char *)_rld_new_inter- face(_RLD_FIRST_PATHNAME) /* Return next path name in object list */ (char *)_rld_new_inter- face(_RLD_NEXT_PATHNAME) /* Modify the object list, see rld_interface.h */ (char *)_rld_new_in- terface(_RLD_MODIFY_LIST, Elf32_Word operation, char *original_path name, char *name) /* Map a virtual address to a name */ (char *)_rld_new_inter- face(_RLD_ADDR_TO_NAME, Elf32_Addr address) /* Map a name to a virtual address */ (Elf32_Addr)_rld_new_inter- face(_RLD_NAME_TO_ADDR, char *name) The following operation codes are used to implement dlopen(3), etc.: /* See dlopen(3) for details */ (void *)_rld_new_inter- face(_RLD_LDR_DLOPEN, char *libname, int mode) /* See dlsym(3) for details */ (void *)_rld_new_interface(_RLD_LDR_DL- SYM, void *handle, char *symname) /* See dlerror(3) for details */ (char *)_rld_new_inter- face(_RLD_LDR_DLERROR) /* See dlclose(3) for details */ (int)_rld_new_interface(_RLD_LDR_DL- CLOSE, void *handle) The following operation codes are used internally by libc and dbx: /* Old support for sbrk(2) */ (int)_rld_new_interface(_RLD_LDR_SBRK, int incr, char **p_oldbrk) /* Old support for brk(2) */ (int)_rld_new_interface(_RLD_LDR_BRK, char *addr) /* Run fini routines (the same as _RLD_SHUTDOWN) */ (int)_rld_new_in- terface(_RLD_LDR_CONTEXT_ATEXIT, ldr_context_t ctxt) /* See ldr_inq_region(3) */ (int)_rld_new_interface(_RLD_LDR_CON- TEXT_INQ_REGION, ldr_context_t ctxt, ldr_module_t mod_id, ldr_region_t re- gion_no, ldr_region_info_t *infop, size_t sizeasked, size_t *sizegot) /* See ldr_inq_module(3) */ (int)_rld_new_interface(_RLD_LDR_CON- TEXT_INQ_MODULE, ldr_context_t ctxt, ldr_module_t mod_id, ldr_module_info_t *infop, size_t sizeasked, size_t *size- got) /* See ldr_next_module(3) */ (int)_rld_new_interface(_RLD_LDR_CON- TEXT_NEXT_MODULE, ldr_context_t ctxt, ldr_module_t *mod_id_ptr) In the above entry points, ctxt is a loader context, allowing the pos- sibility of querying and manipulating various environments. Currently, ctxt must be set to ldr_process_context, which is a symbol resolved by the loader to an internal data structure. This allows operations on the current process. LOADER OPTIONS Users may specify loader options by setting the _RLD_ARGS environment variable to a space separated list of any of the following options: For programs that assume local variable to be initialized to zero upon en- try, this option forces the loader to zero any stack it uses before re- turning to user code. Ignore interface versions on all objects. Ig- nore the interface version checking on the object specified. Does not complain or abort when the loader cannot resolve unresolved data sym- bols. The loader interactively prompts the user on stdin to fix prob- lems in the link (the loader will ask the user to provide a full path name for a missing shared object.) Prints all messages to a log file instead of /dev/tty. Prints all messages to stderr instead of /dev/tty. Prints all messages to stdout instead of /dev/tty. Prints loader statistics to /dev/tty. Prints all actions done for the user by the loader. Prints general actions (less verbose than -trace.) Forces the loader to handle all objects as "truncated address space option" objects. These are objects whose dependencies must be loaded in the lower 31-bit-addressable virtual address range. Shared libraries that have been linked outside of this range will be relocated by the loader. Forces the loader to use a depth_first, ring search method for resolv- ing symbol references between shared objects. For setuid programs not run by the superuser, _RLD_ARGS is ignored. SYMBOL BINDING The loader can resolve symbols using either deferred or immediate bind- ing. Immediate binding requires that all symbols be resolved when an executable program or shared library is loaded. Deferred ("lazy") binding allows text symbols to be resolved at run time by the loader's lazy_text_resolve entrypoint, described above. By default, programs are loaded with deferred binding. If the LD_BIND_NOW environment variable is set to a non-null value, programs will be loaded with immediate binding. SYMBOL RESOLUTION The loader's default symbol resolution policy uses a breadth-first search of the entire dependence graph to resolve symbol references be- tween shared objects. The search starts from the call_shared exe- cutable, traverses dependencies left-to-right and ignores cycles or du- plicates. The depth_ring_search method is an alternative symbol resolution policy which can be selected for an individual executable at link time, or for all executables at run time. See ld(1) for link time options. At run time the loader switch -depth_ring_search is used to enable this symbol resolution policy. The depth_ring_search order is a depth-first search starting from the referencing object, followed by a depth-first search starting from the root. As with the default search policy, the traversal of dependencies is performed left-to-right; cycles and duplicates are ignored. To illustrate these differences, consider the dependence graph defined by the following dependencies: a.out -> libfoo.so libbar.so libc.so libfoo.so -> libc.so libbar.so -> libc.so libc.so -> The default symbol resolution policy uses a single breadth-first search order to resolve symbol references for each of the objects in the pre- ceding example. The order for this example is: Referencing Search Object Order All a.out libfoo.so libbar.so libc.so The depth ring search order depends on which object a symbol reference is being resolved for. The search orders for resolving references from each object in the above example are as follows: Referencing Search Object Order a.out a.out libfoo.so libc.so libbar.so libfoo.so libfoo.so libc.so a.out libbar.so libbar.so libbar.so libc.so a.out libfoo.so libc.so libc.so a.out libfoo.so libbar.so Depth ring search order should be used with caution. The default sym- bol resolution policy ensures that the same symbol is resolved for any object that references it. With depth ring search, you can have multi- ple instances of a symbol, referenced from different objects. This could introduce synchronization problems in execution, particularly if I/O buffers are duplicated across multiple shared libraries. SEE ALSO ld(1), dlopen(3), dlsym(3), dlclose(3), dlerror(3) loader(5)