Object files

Shared object dependencies

When the link editor processes an archive library, it extracts library members and copies them into the output object file. These statically linked services are available during execution without involving the dynamic linker. Shared objects also provide services, and the dynamic linker must attach the proper shared object files to the process image for execution.

When the dynamic linker creates the memory segments for an object file, the dependencies (recorded in DT_NEEDED entries of the dynamic structure) tell what shared objects are needed to supply the program's services. By repeatedly connecting referenced shared objects and their dependencies, the dynamic linker builds a complete process image. When resolving symbolic references, the dynamic linker examines the symbol tables with a breadth-first search. That is, it first looks at the symbol table of the executable program itself, then at the symbol tables of the DT_NEEDED entries (in order), and then at the second level DT_NEEDED entries, and so on. Shared object files must be readable by the process; other permissions are not required.

NOTE: Even when a shared object is referenced multiple times in the dependency list, the dynamic linker will connect the object only once to the process.

Names in the dependency list are copies either of the DT_SONAME strings or the path names of the shared objects used to build the object file. For example, if the link editor builds an executable file using one shared object with a DT_SONAME entry of lib1 and another shared object library with the path name /usr/lib/lib2, the executable file will contain lib1 and /usr/lib/lib2 in its dependency list.

If a shared object name has one or more slash (/) characters anywhere in the name, such as /usr/lib/lib2 or directory/file, the dynamic linker uses that string directly as the path name. If the name has no slashes, such as lib1, three facilities specify shared object path searching.

The dynamic array tag DT_RUNPATH gives a string that holds a list of directories, separated by colons :. For example, the string /home/dir/lib:/home/dir2/lib: tells the dynamic linker to search first the directory /home/dir/lib, then /home/dir2/lib, and then the current directory to find dependencies.
The set of directories specified by a given DT_RUNPATH entry is used to find only the immediate dependencies of the executable or shared object containing the entry. That is, it is used only for those dependencies contained in the DT_NEEDED entries of the dynamic structure containing the DT_RUNPATH entry, itself. One object's DT_RUNPATH entry does not affect the search for any other object's dependencies.
A variable called LD_LIBRARY_PATH in the process environment [see exec(BA_OS)] may hold a list of directories as above, optionally followed by a semicolon ; and another directory list. The following values would be equivalent to the previous example:
- LD_LIBRARY_PATH=/home/dir/usr/lib:/home/dir2/usr/lib:
- LD_LIBRARY_PATH=/home/dir/usr/lib;/home/dir2/usr/lib:
- LD_LIBRARY_PATH=/home/dir/usr/lib:/home/dir2/usr/lib:;
Although some programs (such as the link editor) treat the lists before and after the semicolon differently, the dynamic linker does not. Nevertheless, the dynamic linker accepts the semicolon notation, with the semantics described previously.
All LD_LIBRARY_PATH directories are searched before those from DT_RUNPATH.
Finally, if the other two groups of directories fail to locate the desired library, the dynamic linker searches the default directories, /usr/lib or such other directories as may be specified by the ABI supplement for a given processor.

When the dynamic linker is searching for shared objects, it is not a fatal error if an ELF file with the wrong attributes is encountered in the search. Instead, the dynamic linker shall exhaust the search of all paths before determining that a matching object could not be found. For this determination, the relevant attributes are contained in the following ELF header fields: e_ident[EI_DATA], e_ident[EI_CLASS], e_ident[EI_OSABI], e_ident[EI_ABIVERSION], e_machine, e_type, e_flags and e_version.

NOTE: For security, the dynamic linker ignores LD_LIBRARY_PATH for set-user and set-group ID programs. It does, however, search DT_RUNPATH directories and the default directories. The same restriction may be applied to processes that have more than minimal privileges on systems with installed extended security mechanisms.

NOTE: A fourth search facility, the dynamic array tag DT_RPATH, has been moved to level 2 in the ABI. It provides a colon-separated list of directories to search. Directories specified by DT_RPATH are searched before directories specified by LD_LIBRARY_PATH.

If both DT_RPATH and DT_RUNPATH entries appear in a single object's dynamic array, the dynamic linker processes only the DT_RUNPATH entry.

Substitution sequences

Within a string provided by dynamic array entries with the DT_NEEDED or DT_RUNPATH tags and in pathnames passed as parameters to the dlopen() routine, a dollar sign $ introduces a substitution sequence. This sequence consists of the dollar sign immediately followed by either the longest name sequence or a name contained within left and right braces { and }. A name is a sequence of bytes that start with either a letter or an underscore followed by zero or more letters, digits or underscores. If a dollar sign is not immediately followed by a name or a brace-enclosed name, the behavior of the dynamic linker is unspecified.

If the name is ``ORIGIN'', then the substitution sequence is replaced by the dynamic linker with the absolute pathname of the directory in which the object containing the substitution sequence originated. Moreover, the pathname will contain no symbolic links or use of . or .. components. Otherwise (when the name is not ``ORIGIN'') the behavior of the dynamic linker is unspecified.

When the dynamic linker loads an object that uses $ORIGIN, it must calculate the pathname of the directory containing the object. Because this calculation can be computationally expensive, implementations may want to avoid the calculation for objects that do not use $ORIGIN. If an object calls dlopen() with a string containing $ORIGIN and does not use $ORIGIN in one if its dynamic array entries, the dynamic linker may not have calculated the pathname for the object until the dlopen() actually occurs. Since the application may have changed its current working directory before the dlopen() call, the calculation may not yield the correct result. To avoid this possibility, an object may signal its intention to reference $ORIGIN by setting the DF_ORIGIN flag. An implementation may reject an attempt to use $ORIGIN within a dlopen() call from an object that did not set the DF_ORIGIN flag and did not use $ORIGIN within its dynamic array.

NOTE: For security, the dynamic linker does not allow use of $ORIGIN substitution sequences for set-user and set-group ID programs. For such sequences that appear within strings specified by DT_RUNPATH dynamic array entries, the specific search path containing the $ORIGIN sequence is ignored (though other search paths in the same string are processed). $ORIGIN sequences within a DT_NEEDED entry or path passed as a parameter to dlopen() are treated as errors. The same restrictions may be applied to processes that have more than minimal privileges on systems with installed extended security mechanisms.