dld.sl(5)dld.sl(5)NAMEdld.sl - dynamic loader
MULTITHREAD USAGE
The dynamic loader is thread-safe.
DESCRIPTION
The program is the PA-RISC 64-bit dynamic loader. The program is the
PA-RISC 32-bit dynamic loader. In programs that use shared libraries,
is invoked automatically at startup time by exec on PA-RISC 64-bit sys‐
tems and by the startup file on PA-RISC 32-bit systems. Identical
copies of are kept in both and directories. The dynamic loader is,
itself, a shared library, although it defines no symbols for use by
user programs.
Shared Libraries
Shared libraries are executable files created with the option to (see
ld(1)). They must contain position-independent code (PIC) that can be
mapped anywhere in the address space of a process and executed with
minimal relocation. PIC can use PC-relative addressing modes and/or
linkage tables. It is generated by default by the compilers on PA-RISC
64-bit systems and by specifying the options on PA-RISC 32-bit systems.
See the option to ld(1) or the manual for details on writing PIC in
assembly language.
Incomplete Executables
An executable program linked with one or more shared libraries is
called an
When creating an executable file from object files and libraries, the
linker does not copy text (code) or data from the shared library into
the output file. Instead, the dynamic loader maps the library into the
address space of the process at run time. The linker binds all program
references to shared library routines and data to entries in a linkage
table, and relies on the dynamic loader to fill in the linkage table
entries once the libraries have been mapped. This linkage table serves
as a jump table for function calls.
Thread local storage is now supported. The dynamic loader will tally
each shared library's thread local storage size as well as the pro‐
gram's thread local storage size. When all libraries are loaded on PA-
RISC 32-bit systems, the dynamic loader either calls a thread routine
to set the thread pointer and allocate space for the initial thread or
calls and to allocate the space and setup the thread pointer.
On PA-RISC 64-bit systems, the dynamic loader invokes an initializer in
the system library which will do the thread initialization, allocation
of the initial thread, and set the thread pointer.
On previous PA-RISC 32-bit releases, shared library data items refer‐
enced by the program were copied into the program executable file so
that the data references could be resolved statically. Beginning with
the Series 700/800 10.0 release, references to shared library data from
the are included in a linkage table and are resolved at run time.
Loading
An incomplete executable contains a list of path names of the shared
libraries searched at link time. At run time, the dynamic loader
attaches to the process all shared libraries that were linked with the
program. The dynamic loader will attempt to load each library from the
same directory in which it was found at link time. It is possible to
change the shared library run time search path by specifying a dynamic
path list. See and/or
The text segment of a library is shared among all processes that use
it. The data and bss segments are shared on a page-by-page basis.
When a process first accesses (reads or writes) a data or bss page, a
copy of that page is made for the process.
PARISC 32-bit Dynamic Path List
There are two was to specify a dynamic path list :
· by storing a directory path list in the executable using the
path_list option to
· by linking the executable with option enabling the executable to use
the path list defined by the environment variable at run time.
The path list is a list of one or more path names separated by colons
The dynamic path list will work only for libraries specified with the
or options to However, it can be enabled for libraries specified with a
full path name using the option to (see chatr(1)). If both and are
used, their relative order on the command line indicates which path
list will be searched first in compatibility mode.
See the option to ld(1) or the manual for more details.
PA-RISC 64-bit Dynamic Path List
For standard mode libraries (libraries built or linked with the dynamic
loader will use dynamic path searching to find shared libraries whose
names appear in the shared library list of the program or loaded shared
libraries with no embedded character. Dynamic path searching is
enabled by default for these standard mode libraries or executables.
If is specified, the dynamic loader will not look at any dynamic path
environment variables to find dependent shared libraries. This limits
the dynamic path searching to the value of and the default directories
and
For compatibility mode libraries (libraries built or linked with the
dynamic loader will only do dynamic path searching for these libraries
if they were linked with or and one of these were specified:
·
·
·
There are several ways to specify a dynamic path list :
· By storing a directory path list in the executable using the option
to
· By not specifying and letting the linker set the value to a concate‐
nation of the path_list followed by the value of the environment
variable followed by the default directories and This is for stan‐
dard mode shared libraries only.
· By storing a directory path list in the environment variables and/or
For compatibility mode shared libraries and executables, the direc‐
tory path_list should only be put in the environment variable.
The path list is a list of one or more path names separated by colons
The dynamic path list will work only for libraries specified with the
or options to However, it can be enabled for libraries specified with a
full path name using the option to (see chatr(1)). If both and are
used, their relative order on the command line indicates which path
list will be searched first in compatibility mode.
See the option to ld(1) or the manual for more details.
The dynamic loader will use these rules when determining which dynamic
path list to use:
· If was specified and and were not specified, then the only dynamic
path searching that can be done is to look at the path list in fol‐
lowed by the default directories and
· If was specified and and were not specified, no shared library is
subject to dynamic path searching.
· If the and options are not specified, then the path_list in the
environment variable is searched, followed by the path_list in the
environment variable, followed by the path_list in followed by the
default directories and
· If the and are specified, then use the relative ordering of and to
determine if the dynamic loader should use the path_list in before
followed by the library as specified in the shared library list. If
is specified first, use the path_list in first.
The rules change slightly when looking for dependent shared libraries.
· For standard mode libraries, the path_list in the environment vari‐
able is searched first, followed by the path_list in the environment
variable, followed by the value in the parent shared library's fol‐
lowed by the default directories and
The ancestors of a parent shared library may contain a path_list in
but this is ignored when searching for dependent shared libraries of
this parent. Only the parent's is used. If a library with the same
basename (library name without a path) has already been loaded for
the program, that library is used to resolve the dependent shared
library.
· For compatibility mode libraries, the search is the same as for par‐
ent shared libraries, except can be passed from parent shared
libraries to child dependent shared libraries to that child's depen‐
dents, et cetera.
Binding
The dynamic loader also resolves symbolic references between the exe‐
cutable and libraries. By default, function calls are trapped via the
linkage table and bound on first reference. References to data symbols
and other absolute address references cannot be trapped. They are
bound on the first resolution of a function call that could potentially
reference the object.
If the option to is used, the loader binds all necessary references at
startup time. This increases the startup cost of a program, but
ensures that no more binding operations will be required later. Thus,
better real-time response may result, and the risk of a later abort due
to unresolved externals is eliminated.
The tool can be used to improve the start-up time of programs that use
shared libraries (incomplete executables). The tool performs analysis
on the shared library routines and data used to bind the symbols and
stores this information in the executable file. The dynamic loader
will notice that this information is available, and it will use this
fastbind information to bind the symbols instead of the standard search
method.
For more details refer to fastbind(1) and the option to ld(1) or the
manual.
Breadth-first Searching
This is only available on PA-RISC 64-bit systems. By default, the
dynamic loader will do breadth-first searching when binding symbols.
If the incomplete executable was linked with or if a is being executed,
then depth-first searching is used.
Breadth-first searching specifies that the dynamic loader will look for
symbols starting with the incomplete executable followed by all loaded
shared libraries in a left to right order until the symbol is found.
For example, the incomplete executable is searched followed by all
libraries in its shared library list. Then the dependent shared
libraries of the first library in the shared library list is searched,
followed by the dependent shared libraries of the second library in the
list, et cetera.
Depth-first Searching
This is the only search behavior on PA-RISC 32-bit systems and is used
on PA-RISC 64-bit systems if doing a or if the incomplete executable
was linked with The dynamic loader will search the incomplete exe‐
cutable followed by the first library in its shared library list. The
first dependent library of this library is then searched, followed by
the first dependent of this dependent, and so on. When there are no
more dependents, the siblings and their dependents are searched until
eventually the second library in the program's shared library list is
searched, followed by the first dependent of this library, et cetera.
Version Control
Since code from a shared library is mapped at run time from a separate
shared library file, modifications to a shared library may alter the
behavior of existing executables. In some cases, this may cause pro‐
grams to operate incorrectly. Two means of version control is provided
to solve this problem. This is available on PA-RISC 32-bit systems
only. Whenever an incompatible change is made to a library interface,
both versions of the affected module or modules are included in the
library. A mark indicating the date (month/year) the change was made
is recorded in the new module via the pragma in C, or the compiler
directive in Fortran and Pascal.
This date applies to all symbols defined within the module. A high
water mark giving the date of the latest incompatible change is
recorded in the shared library, and the high water mark for each
library linked with the program is recorded in the incomplete exe‐
cutable file. At run time, the dynamic loader checks the high water
mark of each library and loads the library only if it is at least as
new as the high water mark recorded at link time.
When binding symbolic references, the loader chooses the latest version
of a symbol that is not later than the high water mark recorded at link
time. These two checks help ensure that the version of each library
interface used at run time is the same as was expected at link time.
Intra-library versioning may be removed in a future release. The sec‐
ond way for users to version their libraries is by using a new naming
convention, where n is a numeral that is incremented with every new
release of the library. When using the new naming scheme, users must
specify an internal name for the shared library by using the option to
when building the shared library. This internal name is recorded in
each incomplete executable or shared library that links with the shared
library.
At run time, the loader will look at the shared library list recorded
in the incomplete executable file or shared library. For each library
in the list that was not an internal name, the dynamic loader will look
for a version of the library (e.g. to load. If it does not find this
version, it will look for the library name that is recorded in the
list.
PA-RISC 32-bit Explicit Loading and Binding
The duties of the dynamic loader as described above are all performed
automatically, although they can be controlled somewhat by appropriate
options to The dynamic loader can also be accessed programmatically.
The reserved symbol which is defined in points to a jump table within
the dynamic loader.
The routines described under shl_load(3X) provide a portable interface
that allows the programmer to explicitly attach a shared library to the
process at run time, to calculate the addresses of symbols defined
within shared libraries, and to detach the library when done.
PA-RISC 64-bit Explicit Loading and Binding
The duties of the dynamic loader as described above are all performed
automatically, although they can be controlled somewhat by appropriate
options to The dynamic loader can also be accessed programmatically.
The routines described under shl_load(3X), dlclose(3C), dlerror(3C),
dlget(3C), dlmodinfo(3C), dlopen(3C), and dlsym(3C) provide a portable
interface that allows the programmer to explicitly attach a shared
library to the process at run time, to calculate the addresses of sym‐
bols defined within shared libraries, and to detach the library when
done.
Global Symbol Table
The global symbol table mechanism is designed as a performance enhance‐
ment option. Enabling this mechanism causes the creation of a global
symbol table which speeds up symbol lookup, by eliminating the need to
scan all loaded libraries in order to find a symbol. Instead, this
mechanism allows the dynamic loader to scan one table which contains
the symbol information from all the loaded libraries. This is particu‐
larly effective for applications with large numbers of shared
libraries. This mechanism is off by default.
The global symbol table is implemented using a hash table. Under this
mechanism, whenever a library is loaded (either implicitly or by using
or the mechanism hashes the library's export symbols and places them
into this table. When a library is unloaded, the mechanism looks up
the library's export symbols in the table and removes them.
The hash table does not contain entries for symbols defined by User-
defined symbols must therefore be handled separately.
Enabling the mechanism causes to use more memory and impacts the per‐
formance of the and API calls.
The global symbol table mechanism can force the dynamic loader to per‐
form a large number of hashing operations to locate symbols. Perform‐
ing this hash function can cost considerable time, especially when sym‐
bol names are very long (C++ programs). To speed up the loader, you
can off-load computing hash values to the linker by using the option.
This causes the linker to compute the hash value for all symbols
exported from libraries listed on the link line, and store the hash
values in the executable. At run time, the loader then builds the
global symbol table in memory and reads the stored hash values from the
executable as each library is loaded.
If you do not specify at link time, you can use the option of the
chatr(1) command to enable the global symbol table mechanism, which
causes the loader to build the table and compute the hash values at run
time.
Use the GST options (with the and commands), (PA-RISC 32-bit only),
(PA-RISC 64-bit systems only), and (PA-RISC 32-bit systems only) to
control the behavior of the global symbol table hash mechanism. You
can use the and linker/chatr options to control the behavior of the
global symbol table hash mechanism.
With the GST options, you can tune the size of the hash table and num‐
ber of buckets per entry to reach a balance of performance and memory
use. To maximize for performance, tune the table size for an average
chain length of one. For maximum memory use, at the expense of perfor‐
mance, tune the size of the table to minimize the number of empty
entries. In general, use prime numbers for the table size. The mecha‐
nism provide default values of table size, 1103, and number of buckets,
3.
To get statistical information about hash table performance, set the
environment variable to contain the and options. This combination of
options provides a message for each library that contains the following
information:
· Operation (load/unload)
· Name of library
· Number of export symbols
· Number of entries in table with no stored symbols
· Average length of non-zero chains
· Calculated performance of the hash table
· Amount of memory used by the hash table
See the ld(1) and chatr(1) commands for information on the and options.
The LD_PRELOAD Environment Variable
NOTE: The feature is disabled for programs, such as See ld(1) for more
details. This feature is not available to fully-bound static executa‐
bles.
The environment variable allows you to load additional shared libraries
at program startup. provides a colon-separated or space-separated list
of shared libraries that the dynamic loader can interpret. The dynamic
loader, loads the specified shared libraries as if the program had been
linked explicitly with the shared libraries in before any other depen‐
dents of the program.
At startup time, the dynamic loader implicitly loads one or more
libraries, if found, specified in the environment. It uses the same
load order and symbol resolution order as if the library had been
explicitly linked as the first library in the link line when building
the executable. For example, given an executable built with the fol‐
lowing link line:
If the dynamic loader uses the same load order and symbol resolution
order as if had been specified as the first library in the link line:
In a typical command line use (with where is defined as follows:
The dynamic loader searches application according to but searches
according to and/or and/or the embedded path (if enabled).
NOTE: Because the dynamic loader checks the environment variable when
running any executable (except seteuid/setegid programs), if you export
you should unset it after running your executable, or run the exe‐
cutable as in the command listed above or in a script.
NOTE: The linker and tools do not require any shared library to be pre‐
loaded. Invoking any of them with either the or environment variable
set is unsupported and may result in undefined behaviour.
You can use the environment variable to load a shared library that con‐
tains thread-local storage to avoid the following error when loading
the library dynamically:
The load order and symbol resolution order may be different in a PA-
RISC 32-bit program than in the same PA-RISC 64-bit program because the
dynamic loader uses depth-first search order in PA-Risc 32-bit mode and
breadth-first search order in PA-RISC 64-bit mode.
See in the option to ld(1) or the for more information.
The dynamic loader uses the environment variable even if you use the in
the link line. This insures that is enabled even in a link. The vari‐
able is always enabled except for and programs.
NOTE: If an archive library is already linked-in with the application
and we try to load the shared version of that library using we will
have problems.
The potential problems are :
· If the library has initializers/terminators, they will be
called twice
· you may end up using two different copies of the same data
symbol which may cause incorrect behavior
You can specify multiple libraries as part of the environment variable.
Separate the libraries by spaces or colons as in (Multi-byte support is
not provided as part of parsing the library list). You can specify
libraries with absolute paths or relative paths. The libraries can
also consist of just the library names, in which case the dynamic
loader uses the directory path list in the environment variables and/or
or the embedded path list (if enabled) to search for the libraries.
The dynamic loader does not issue an error or warning message if it
cannot find a library specified by However, if it does not find a
dependent of the libraries, the dynamic loader issues the same error
message as if the library is specified in the link line.
The LD_PRELOAD_ONCE Environment Variable
The feature is similar to except that the dynamic loader, unsets after
reading it, so that any applications invoked by the current application
do not have set. This is useful in situations where the current appli‐
cation needs certain libraries preloaded while the child application is
adversely affected if these are preloaded (for example, terminates
abnormally if contains
The libraries specified by are loaded before the ones specified by The
effect on symbol resolution is that the symbols from libraries speci‐
fied by take precedence over symbols from libraries specified by
Running setuid Programs
For looking up shared libraries for applications, the dynamic loader
uses only the paths listed in
If and are set, they are validated against the list of paths in (This
allows the individual applications to appropriately order the list from
the file).
You can turn this feature off by setting the option to Using this
option disables programs from all dynamic path lookup.
The configuration file is expected to contain a list of shared library
search paths (delimited by either colon or newline characters). To
avoid redundant searches, you should see that one path appears only
once in the file (and also in the options and
The file should be writeable only by Otherwise, the loader does not use
its contents. If does not exist or has the wrong permissions, all
dynamic path lookup is disabled. Any relative paths (paths not start‐
ing with slash in the path list are ignored by the loader.
NOTE: Spaces are not allowed in the paths listed. Everything on a line
that follows a space or pound character is ignored. You can use the
pound sign to comment out paths in the file.
If either or is set, and neither contains any path listed in the file,
all dynamic path lookup is disabled. The paths from the file are not a
fallback.
The following is a sample configuration file:
# need this for some GNU and shared apps
/usr/local/lib:/nfs/appserver/lib
# path below is ignored: path not starting with '/'
# and loader will not expand ~ etc.
~wizkid/lib
# second path below ignored: space
/user/ipfguru/lib/hpux32: user/ipfguru/lib/hpux64
/net/appserv2/local/lib # ignored:line starting with space
/opt/java1.3/jre/lib/PA_RISC2.0/ # java 1.3 PA32
/opt/java1.3/jre/lib/PA_RISC2.0/server # java 1.3 PA32
/opt/java1.3/jre/lib/PA_RISC2.0W/
# java 1.4
/opt/java1.4/jre/lib/PA_RISC2.0/:/opt/java1.4/jre/lib/PA_RISC2.0/server
/opt/java1.4/jre/lib/PA_RISC2.0W/:/opt/java1.4/jre/lib/PA_RISC2.0W/server
DIAGNOSTICS
If the dynamic loader is not present, or cannot be invoked by the
process for any reason, an error message is printed to standard error
and the process terminates with a non-zero exit code.
These errors fall into two basic categories: errors in attaching a
shared library, and errors in binding symbols. The former can occur
only at process startup time but the latter can occur at any time dur‐
ing process execution unless the option is used with Possible errors
that can occur while attaching a shared library include library not
present, library not executable, library corrupt, high water mark too
low, or insufficient room in the address space for the library. Possi‐
ble errors that can occur while binding symbols include symbol not
found (unresolved external), or library corrupt.
When using the explicit load facilities of the dynamic loader, these
types of errors are not considered fatal. Consult shl_load(3X),
dlclose(3C), dlget(3C), dlgetname(3C), dlmodinfo(3C), dlopen(3C), and
dlsym(3C) for more information. On PA-RISC 64-bit systems, to see
error messages, use the routine. This routine will print the last
error message recorded by the dynamic loader.
WARNINGS
The startup cost of the dynamic loader is significant, even with
deferred binding, and can cause severe performance degradation in pro‐
cesses dominated by startup costs (such as simple ``hello world'' pro‐
grams). In addition, position-independent code is usually slower than
normal code, so performance of a program may be adversely affected by
the presence of PIC in shared libraries. However, the advantages of
decreased disk space usage and decreased memory requirements for exe‐
cutables should outweigh these concerns in most cases.
There are rare cases where the behavior of a program differs when using
shared libraries as opposed to archive libraries. This happens primar‐
ily when relying on undocumented and unsupported features of the com‐
pilers, assembler, and linker.
See the option to ld(1) or the manual for more details.
The library developer is entirely responsible for version control and
must be thorough in identifying incompatible changes to library inter‐
faces. Otherwise, programs may malfunction unexpectedly with later
versions of the library. There is little an application user can do if
version control is not handled properly by the library developer. The
application developer can usually resolve problems by modifying the
source code to use the new interfaces then recompiling and relinking
against the new libraries.
By default, most warnings are not reported by the dynamic loader.
On PA-RISC 32-bit systems, if you wish to see all of the messages, set
the environment variable to contain one or more options. The following
options are supported:
Display additional dynamic loader warning messages. Some of
these include:
· Symbols of the same name but different types, such as
CODE and DATA. See the section in ld(1) for more
details on this warning.
· Using certain flags or routines described in
shl_load(3X).
See fastbind(1).
See fastbind(1).
Display verbose messages concerning possible unsatisfied sym‐
bols.
This is equivalent to of and of calls. This option can be
used in cases where the application has already been
built without either or and verbose messages are
expected. Currently, this is applicable only for PA32.
On PA-RISC 64-bit systems, if you wish to see all error messages, set
the environment variable to true.
AUTHOR
The and shared libraries were developed by HP.
FILES
list of shared libraries for lookup with
programs
SEE ALSO
System Tools
aCC(1) invoke the HP-UX aC++ compiler
as(1) translate assembly code to machine code
CC(1) invoke the HP-UX C++ compiler
cc(1) invoke the HP-UX C compiler
chatr(1) change program's internal attributes
f77(1) invoke the HP-UX FORTRAN compiler
f90(1) invoke the HP-UX Fortran 90 compiler
fastbind(1) invoke the fastbind tool
ld(1) invoke the link editor
pc(1) invoke the HP-UX Pascal compiler
Miscellaneous
a.out(4) assembler, compiler, and linker output
dlclose(3C) unload a shared library previously loaded by
dlerror(3C) print the last error message recorded by dld
dlget(3C) return information about a loaded module
dlgetname(3C) return the name of the storage containing a load mod‐
ule
dlmodinfo(3C) return information about a loaded module
dlopen(3C) load a shared library
dlsym(3C) get the address of a symbol in a shared library
shl_load(3X) load/unload shared libraries
Texts and Tutorials
(See the option to ld(1))
(See manuals(5) for ordering information)
PA-RISC Systems Only dld.sl(5)
