dld.sl(5)							File Formats Manual							 dld.sl(5)

NAME

       dld.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 systems 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 sys-
       tems.

       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 link-
       age 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 rou-
       tine 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, alloca-
       tion of the initial thread, and set the thread pointer.

       On  previous  PA-RISC  32-bit releases, shared library data items referenced 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 :

       o  by storing a directory path list in the executable using the path_list option to

       o  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 lim-
       its 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:

       o
       o
       o

       There are several ways to specify a dynamic path list :

       o  By storing a directory path list in the executable using the option to

       o  By  not  specifying  and  letting  the linker set the value to a concatenation of the path_list followed by the value of the environment
	  variable followed by the default directories and This is for standard mode shared libraries only.

       o  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:

       o  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

       o  If was specified and and were not specified, no shared library is subject to dynamic path searching.

       o  If the and options are not specified, then the path_list in the environment variable is searched, followed by the path_list in the envi-
	  ronment variable, followed by the path_list in followed by the default directories and

       o  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.

       o  For standard mode libraries, the path_list in the environment variable is searched first, followed by the path_list in  the  environment
	  variable, followed by the value in the parent shared library's followed 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.

       o  For  compatibility  mode  libraries,	the  search  is  the  same as for parent shared libraries, except can be passed from parent shared
	  libraries to child dependent shared libraries to that child's dependents, et cetera.

   Binding
       The dynamic loader also resolves symbolic references between the executable 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 analy-
       sis  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  stan-
       dard 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 executable 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 programs 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	executable
       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 second 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 appropri-
       ate 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  appropri-
       ate 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 enhancement 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 partic-
       ularly 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 performance of the and API calls.

       The global symbol table mechanism can force the dynamic loader to perform a large number of hashing operations to locate symbols.  Perform-
       ing  this hash function can cost considerable time, especially when symbol 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 number 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  per-
       formance, tune the size of the table to minimize the number of empty entries.  In general, use prime numbers for the table size.  The mech-
       anism 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 option.  This  option  provides  a
       message for each library that contains the following information:

       o  Operation (load/unload)
       o  Name of library
       o  Number of export symbols
       o  Number of entries in table with no stored symbols
       o  Average length of non-zero chains
       o  Calculated performance of the hash table
       o  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 seteuid/setegid programs, such as See ld(1) for more details.  This feature is not available to fully-
       bound static executables.

       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 dependents 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 exe-
       cutable.  For example, given an executable built with the following 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 executable as in the command listed above or in a script.

       You  can use the environment variable to load a shared library that contains 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
       variable 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 :

	      o  If the library has initializers/terminators, they will be called twice

	      o  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 sup-
       port 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 applica-
       tion do not have set.  This is useful in situations where the current application needs certain libraries preloaded while the child  appli-
       cation 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 spec-
       ified 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 starting 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 during 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.  Possible 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'' programs).  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 executables 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
       primarily when relying on undocumented and unsupported features of the compilers, 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
       interfaces.   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  modify-
       ing 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 fol-
       lowing options are supported:
	      Display additional dynamic loader warning messages.  Some of these include:

		     o 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.

		     o Using certain flags or routines described in shl_load(3X).

	      See    fastbind(1).

	      See    fastbind(1).

	      Display verbose messages concerning possible unsatisfied symbols.
		     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 module
       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)