LD.SO(8) BSD System Manager's Manual LD.SO(8)NAME
ld.so, ld-bsdi.so - the ELF dynamic linker
DESCRIPTION
The ELF dynamic linker ld.so is a program that links and loads ELF shared
libraries and shared objects into an application program when you run the
application program. The shared object /shlib/ld-bsdi.so is the BSD/OS-
specific version of the dynamic linker.
An application that is dynamically linked must specify the dynamic linker
as its ELF `interpreter' (see elf(5)). The system arranges to load both
the dynamic linker and the application into memory when you execute the
application, and it gives control to the dynamic linker. The dynamic
linker has access to the application's special ELF dynamic symbol table,
its list of required shared libraries, and other ELF data structures, and
it processes this information to create a complete version of the program
in memory. The dynamic linker uses a search path to locate shared li-
braries and loads each of the requested libraries into memory. The dy-
namic linker relocates the libraries (modifies them to refer to their ac-
tual address, rather than the address that they were originally linked
at) and then links them with the application. For every function or data
object that the application or a shared library needs but doesn't define
itself, the dynamic linker will check for the name of the function or ob-
ject in the shared libraries, and it will patch a pointer to that func-
tion or object in the application (or another shared library) so that it
contains the actual address of the function or object. If the linker can
safely postpone linking, it will; for example, the linker will direct a
call to a library function to a `stub' that computes the correct function
address and stores it so that it can be used again. Once the linker has
relocated the libraries and linked them with the application and with
each other, it transfers control to the application and your program
runs. The application can give control back to the linker to perform
more linking, either implicitly (as with the function stubs) or explicit-
ly using the dynamic linking library (see dlopen(3)).
Dynamically linked applications are easy to create. The compilers gener-
ate dynamically linked executables by default. In fact, you must specify
the flag -static to suppress dynamic linking.
Shared libraries and shared objects must be built in a specific way for
dynamic linking:
o All object files in a shared library or shared object must be com-
piled for position independent code (PIC). With the C compiler cc(1),
use the -fPIC option to compile for PIC. Note that the application
must not be compiled for PIC; only shared libraries and shared ob-
jects should be compiled this way. (Position independent assembly
code must either avoid referring to external functions or data, or
else it must make indirections through the global offset table (GOT)
and procedure linkage table (PLT). Compiling a C source file to as-
sembly code using -fPIC -S will show you what you need to know.)
o A shared library or shared object must be linked using the linker
ld(1) flag -shared. The compiler cc(1) also supports this flag, and
because it provides useful start-up files and libraries, it is usual
to link with cc -shared. A relocatable object file (ends in .o) must
be converted into a shared library or a shared object (ends in .so)
before it may be loaded by the dynamic linker. For example:
cc -o obj.so -shared obj.o
More than one relocatable object file may be combined into a single
shared library or shared object.
o A shared library should have a library name. This feature allows li-
braries with version number suffixes or other pathname changes to be
treated similarly. The -h flag to the linker ld(1) specifies the
name of the shared library:
cc -o libx.so.1.1 -shared -Wl,-h,libx.so.1 *.o
A shared library is simply a shared object with a library name. Note
that the major shared library version number is appended to the li-
brary name, while both the major and minor numbers appear in the
filename. This is because there is a convention that versions of a
library with the same major version number and different minor ver-
sion numbers are compatible, while versions of a library with differ-
ent major version numbers are incompatible. By including the major
version number in the library name, the dynamic linker will be forced
to choose only compatible versions of the library.
o If a shared library or shared object requires functions or data from
another shared library or shared object, you should note this depen-
dency when linking the shared library or shared object. For example,
if libx.so uses math library functions, then it should be linked
against the shared math library:
cc -o libx.so.1.1 -shared -Wl,-h,libx.so *.o -lm
If you don't describe these dependencies, then you are relying on the
application or other libraries to load the other libraries and ob-
jects that you need, which is risky.
Once you have built a shared library, you will need to install it. The
dynamic linker reads the file /etc/ld.so.conf to obtain the list of stan-
dard directories for shared libraries and the order in which to check
them. The file /etc/ld.so.cache is a database that maps library names to
pathnames in the standard directories. You can use the program ldcon-
fig(8) to build this file and to list the mappings in the file. You can
override the default path (see below). Note that ldconfig(8) can recog-
nize multiple library `versions'; see the manual page for more details.
Certain features of the dynamic linker may be controlled by environment
variables:
LD_BIND_NOW If this variable is set and not null, the dynamic link-
er will perform all function address linking and relo-
cation for a library when it loads it. Normally the
dynamic linker will delay linking functions until they
are called. This feature is exactly analogous to the
RTLD_NOW feature of dlopen(3), but it acts only on
shared libraries.
LD_LIBRARY_PATH If this variable is set, the dynamic linker treats the
value as a colon (`:') separated list of directories in
which to search for shared libraries and shared ob-
jects. This path is searched after the `run path' (see
LD_RUN_PATH below) and before the default path from
/etc/ld.so.conf. Setuid or setgid programs unset
LD_LIBRARY_PATH and ignore its value.
LD_PRELOAD If this variable is set, the dynamic linker treats the
value as a list of colon or whitespace separated file-
names of shared libraries. If the program is neither
setuid nor setgid, the linker will load these libraries
before loading the libraries requested by the program.
This allows you to interpose alternate libraries, so
that functions and data in the alternate libraries take
precedence over functions and data in the standard li-
braries. Setuid or setgid programs unset LD_PRELOAD
and ignore its value.
LD_RUN_PATH Unlike the other variables described here, this vari-
able affects the regular linker ld(1). If this vari-
able is set when ld(1) creates a dynamically linked ex-
ecutable, the value is treated as a list of colon-sepa-
rated directories called the `run path'. The linker in-
serts the run path into a dynamically linked program,
and when you execute the program, the dynamic linker
checks the directories in the list for shared libraries
and shared objects. The dynamic linker checks the run
path before LD_LIBRARY_PATH and before the default di-
rectories listed in /etc/ld.so.conf. Note that the dy-
namic linker does not read the value of LD_RUN_PATH;
only ld(1) checks the value. The ld(1) flag -rpath
provides another way to set the run path (see the ld(1)
manual page).
The ldd(1) program prints the names of shared libraries and shared ob-
jects that the dynamic linker loads. See the manual page for details.
You can call the dynamic linker directly from user code. The dlsym(3)
function will convert a string into the address of the named function or
data object. See the manual page for details.
ENVIRONMENT
LD_BIND_NOW forces immediate linking for functions
LD_LIBRARY_PATH directory search-path for object files
LD_PRELOAD libraries to load before anything else
LD_RUN_PATH make ld(1) set the search path
ERRORS
The dynamic linker may print one of the following error messages, where
%s is replaced by the name of a file:
can't load library '%s'
can't open file '/etc/ld.so.preload'
can't map file '/etc/ld.so.preload'
can't handle REL relocation records
can't handle RELA relocation records
can't map '/dev/zero'
can't open cache '/etc/ld.so.cache'
can't map cache '/etc/ld.so.cache'
cache '/etc/ld.so.cache' is corrupt
'%s' is not an ELF file
'%s' is not an ELF executable for ${MACHINE}
'%s' has more than one dynamic section
can't map '%s'
'%s' is missing a dynamic section
SEE ALSOcc(1), ld(1), ldd(1), dlopen(3), elf(5), shlist(8)ACKNOWLEDGEMENTS
The source code for the dynamic linker is derived from Linux's ld.so
(/lib/ld-linux.so), and it is believed to be compatible with the Solaris
dynamic linker. The authors of the Linux dynamic linker are David Engel,
Eric Youngdale, Peter MacDonald, Hongjiu Lu, Linus Torvalds, Lars Wirze-
nius and Mitch D'Souza.
BSDI BSD/OS October 11, 1999 3