Legal Notices

Table of Contents

What's New in Recent Releases

Intermediate Update:

Pthread stubs in HP C library

The HP-UX March 2001 linker toolset contains new features:

Loading Shared Libraries with the LD_PRELOAD Environment Variable,describes ho to use the LD_PRELOAD environment variable with shared libraries.

32-bit support for the +init and +fini initializer/finalizer options. See Initializers for Shared Librariesfor more information.

Virtual Environment Support for HP-UX kernel. See for ld(1) for more information.

Improving Performance with Function Symbol Aliasing describes link time function name aliasing to improve performance.

The HP-UX 11i linker toolset contains new features:

Viewing library dependencies with ldd(1). 32-bit support for the ldd(1) linker tool.

32-bit support for the dl*(3C) shared library management routines, dlopen, dlclose, dlsym, and dlerror. See Shared Library Management Routines for more information.

+objdebugonly option. See for ld(1) for more information.

Odump dump utility to display the contents of a 32-bit native code (SOM) object file. See odump(1) for more information.

gprof 32-bit support for profiling shared libraries. The gprof tool is used to produce profile information about an executable. Enhancements in this release enable these tools to work with incomplete executables and shared libraries. Note that you can profile one and only one incomplete executable or shared library at a time. See Profiling Shared Libraries with gprof(1) and gprof(1) for more information.

Using filtered shared libraries (32-bit mode only). 32-bit support for filtered shared libraries.

Incremental Linking. 64-bit support for incremental linking.

The HP-UX 10.20 and 11.x releases contain performance enhancements:

Reusing Compiled Object Files

Improving Performance with the Global Symbol Table

The HP-UX 11.00 linker toolset contains new features:

If you use the 32-bit mode linker toolset, see the following items:

PA-RISC Changes in Hardware Compatibility updated in this chapter.

Exporting Symbols with +ee.

Changes in Future Releases updated in this chapter.

PA-RISC Changes in Hardware Compatibility updated in this chapter.

64-bit Mode Linker Toolset Compatibility with De Facto Industry Standards described in this chapter.

64-bit Mode ELF Object File Format described in this chapter.

Dynamic Path Searching for Shared Libraries describes differences in the run time searching of shared libraries.

Shared Library Symbol Binding Semantics describes differences in shared library binding semantics.

New 64-bit mode linker options, symbols, and features, described inNew Features for 64-bit Mode Linking in this chapter.

Unsupported 32-bit mode features, behavior, and linker options, described in 64-bit Mode Link-time Differences and64-bit Mode Run Time Differences in this chapter.

Using Init/Fini Initializers describes the init/fini support for 64-bit mode shared libraries.

The dlopen Shared Library Management Routines describes the dl* family of shared library management routines for 64-bit mode.

BIND_BREADTH_FIRST Modifier describes the flag added to the shl_load routine to modify search behavior.

Changes in Future Releases updated in this chapter.

The following items were added in the HP-UX 10.30 release:

Linker Thread-Safe Features.

Options to Improve TLB Hit Rates .

The +k linker option (see ld(1)) to remove an executable if the link fails.

The +kchatr option (see chatr(1)) to improve branch prediction on PA-RISC 2.0.

Improving Shared Library Performance with -B symbolic.

Improving Shared Library Start-Up Time with fastbind .

Online Help for Linker and Libraries described in this chapter.

PA-RISC Changes in Hardware Compatibility described in this chapter.

Linker Compatibility Warnings.

Dynamic Loader Compatibility Warnings.

The +Ostaticprediction linker option described in the ld(1) man page to use with profile-based optimization

PA-RISC Changes in Hardware Compatibility

In previous releases, the compilers generated PA-RISC 1.0 code on all HP 9000 Series 800 servers and PA-RISC 1.1 code on Series 700 workstations. HP compilers now by default generate PA-RISC 1.1 code on 1.1 systems and 2.0 code on 2.0 systems.

Using the +DAportable compiler option provides compatibility of code between PA-RISC 1.1 and 2.0 systems. Note that the HP-UX 10.10 release is the last supported release for PA-RISC 1.0 systems, so 1.1 and 2.0 code generated by the HP-UX 10.20 release (or later) of HP compilers is not supported on PA-RISC 1.0 systems.

PA-RISC 2.0 Compatibility

/usr/ccs/bin/ld: (Warning) At least one PA 2.0 object file 
(sum.o) was detected. The linked output may not run on PA 1.x 
system.

$ a.out
ksh: ./a.out: Executable file incompatible with hardware

PA-RISC Architectures and Their System Models

PA-RISC 1.0

The original version of PA-RISC first introduced on Series 800 servers. The following Series are included: 840, 825, 835/SE, 845/SE, 850, 855, 860, 865, 870/x00, 822, 832, 842, 852, 890, 808, 815, 635, 645.

PA-RISC 1.1

The second version of PA-RISC first introduced on Series 700 workstations. Newer Series 800 systems also use this version of the architecture. The following Series are included: 700, 705, 710, 715, 720, 725, 730, 735, 750, 755, B132L, B160L, B132L+, B180L, C100, C110, J200, J210, J210XC, 742i, 742rt, 743i, 743rt, 745i, 747i, 748i, 8x7, D (except Dx70, Dx80), E, F, G, H, I, K (except Kx50, Kx60, Kx70), T500, T520.

PA-RISC 2.0

The newest version of PA-RISC. The following Series are included: C160, C180, C180XP, C200, C240, J280, J282, J2240, Dx70, Dx80, Kx50, Kx60, Kx70, T600, V2200.

See your compiler online help or documentation for details on the +DA option.

See the file /opt/langtools/lib/sched.models for a complete list of model numbers and their architectures. Use the command model to determine the model number of your system.

64-bit Mode Linker Toolset Compatibility with De Facto Industry Standards

ELF object file format and libelf(3E) routines

Dynamic path searching

Library-level versioning

dl* family of dynamic loading routines

Breadth-first symbol searching

Creation of default run-time path environment variable (RPATH) if no ld +b is seen on the link line, to improve transition from the 32-bit mode linker.

ld +compat option for compatibility with 32-bit linking and loading behavior.

64-bit Mode ELF Object File Format

The following options instruct the compiler to generate 64-bit ELF object code.
 

Option	Compiler
+DA2.0W	C and aC++
+DD64	C

See the HP-UX Software Transition Toolkit (STK) at http://www.software.hp.com/STK/ for more information on the structure of ELF object files.

New Features for 64-bit Mode Linking

64-bit Mode Linker Options

64-bit Mode Linker-defined Symbols

64-bit Mode Link-time Differences

For more information, see the HP-UX Linker and Libraries Online User Guide (ld +help).

64-bit Mode Run Time Differences

Dynamic path searching for shared libraries.

Symbol searching in dependent libraries.

The following table summarizes the dynamic loader differences between 32-bit and 64-bit mode:
 

Linker and Loader Functions	32-bit Mode Behavior	64-bit Mode Behavior
+s and +b path_list ordering	Ordering is significant.	Ordering is insignificant by default. Use +compat to enforce ordering.
Symbol searching in dependent libraries	Depth-first search order.	Breadth-first search order.  Use +compat to enforce depth first ordering.
Run time path environment variables	No run time environment variables by default. If +s is specified, then SHLIB_PATH is available.	LD_LIBRARY_PATH and SHLIB_PATH are available. Use +noenv or +compat to turn off run-time path environment variables.
+b path_list and -L directories interaction	-L directories recorded as absolute paths in executables.	-L directories are not recorded in executables, if -L and +b are both used. To record all the directories in executables, add all directories specified in -L to +b path_list.

For more information on transition issues, see HP-UX 64-bit Porting and Transition Guide.

Changes in Future Releases

Support of ELF 32 object file format

A future release will support the ELF 32 object file format.

Future of ld +compat option

The +compat linker option and support of compatibility mode may be discontinued in a future release.

Support of shl_load shared library management routines

A future release may discontinue support of the shl_load family of shared library management routines.

Online Help for Linker and Libraries

To access the Linker and Libraries Online User Guide from the ld command line:

ld +help

What Happens When You Compile and Link a Program

Compiling Programs on HP-UX: An Example provides an overview of compiling on HP-UX.

Looking "inside" a Compiler describes the process of creating an executable file in more detail.

Linking Programs on HP-UX describes how ld creates an executable file from one or more object files.

Linking with Libraries describes conventions for using libraries with ld.

Running the Program describes the process of loading and binding programs at run time.

Linker Thread-Safe Featuresdescribes the thread-safe features.

Compiling Programs on HP-UX: An Example

$ cc -Aa sumnum.c

$ a.out
Enter a number: 4
Sum 1 to 4: 10

$ f77 sumnum.f       Compile and link sumnum.f. 
    ...                      The compiler displays any messages here.
$ a.out                     Run the program. 
   ...           Output from the program is displayed here.

$ cc -Aa main.c func.c
main.c:
func.c:

#include <stdio.h>              /* contains standard I/O defs */
int     sum_n( int n )           /* sum numbers from n to 1    */
{
  int   sum = 0;                 /* running total; initially 0 */
  for (; n >= 1; n--)            /* sum from n to 1            */
    sum += n;                   /* add n to sum               */
  return sum;                   /* return the value of sum    */
}
 
main()                          /* begin main program         */
{
  int   n;                      /* number to input from user  */
  printf("Enter a number: ");   /* prompt for number          */
  scanf("%d", &n);              /* read the number into n     */
  printf("Sum 1 to %d: %d\\n", n, sum_n(n)); /* display the sum */
}

Figure 1: High-Level View of the Compiler

Looking "inside" a Compiler

For each source file, the driver calls the language compiler to create an object file. (See Also What is an Object File?.)

Then, the driver calls the HP-UX linker (ld) which builds an a.out file from the object files. This is known as the link-edit phase of compilation. (See Also Compiler-Linker Interaction .)

Figure 2: Looking "inside" a Compiler

The C, C++, FORTRAN, and Pascal compilers provide the -v (verbose) option to display the phases a compiler is performing. Compiling main.c and func.c with the -v option produced this output on a Series 700 workstation (\ at the end of a line indicates the line is continued to the next line):

$ cc -Aa -v main.c func.c -lm
cc: CCOPTS is not set.
main.c:
/opt/langtools/lbin/cpp.ansi main.c /var/tmp/ctmAAAa10102 \\
  -D__hp9000s700 -D__hp9000s800 -D__hppa -D__hpux \\
  -D__unix -D_PA_RISC1_1
cc: Entering Preprocessor.
/opt/ansic/lbin/ccom /var/tmp/ctmAAAa10102 main.o -O0 -Aa \\
  func.c:
/opt/langtools/lbin/cpp.ansi func.c /var/tmp/ctmAAAa10102 \\
  -D__hp9000s700 -D__hp9000s800 -D__hppa -D__hpux \\
  -D__unix -D_PA_RISC1_1
cc: Entering Preprocessor.
/opt/ansic/lbin/ccom /var/tmp/ctmAAAa10102 func.o -O0 -Aa
cc: LPATH is /usr/lib/pa1.1:/usr/lib:/opt/langtools/lib:
/usr/ccs/bin/ld /opt/langtools/lib/crt0.o -u main main.o func.o \\
  -lm -lc
cc: Entering Link editor.

What is an Object File?

To keep track of where all the symbols and external references occur, an object file has a symbol table. The linker uses the symbol tables of all input object files to match up external references to global definitions.

Local Definitions

Global Definitions

External References

Compiler-Linker Interaction

$ cc -Aa -v main.c func.c -lm
cc: CCOPTS is not set.
main.c:
/opt/langtools/lbin/cpp.ansi main.c /var/tmp/ctmAAAa10102 \\
  -D__hp9000s700 -D__hp9000s800 -D__hppa -D__hpux \\
  -D__unix -D_PA_RISC1_1
cc: Entering Preprocessor.
/opt/ansic/lbin/ccom /var/tmp/ctmAAAa10102 main.o -O0 -Aa
func.c:
/opt/langtools/lbin/cpp.ansi func.c /var/tmp/ctmAAAa10102 \\
  -D__hp9000s700 -D__hp9000s800 -D__hppa -D__hpux \\
  -D__unix -D_PA_RISC1_1
cc: Entering Preprocessor.
/opt/ansic/lbin/ccom /var/tmp/ctmAAAa10102 func.o -O0 -Aa
cc: LPATH is /usr/lib/pa1.1:/usr/lib:/opt/langtools/lib:
/usr/ccs/bin/ld /opt/langtools/lib/crt0.o -u main main.o
func.o -lm -lc
cc: Entering Link editor.

In 64-bit mode, the startup functions are handled by the dynamic loader, dld.sl. In most cases, the ld command line does not include crt0.o.

Linking Programs on HP-UX

In the C program example (see Compiling Programs on HP-UX: An Example ) main.o contains an external reference to sum_n, which has a global definition in func.o. ld matches the external reference to the global definition, allowing the main program code in a.out to access sum_n (see Figure 3: Matching the External Reference to sum_n ).

Figure 3: Matching the External Reference to sum_n

If ld cannot match an external reference to a global definition, it displays a message to standard error output. If, for instance, you compile main.cwithoutfunc.c, ld cannot match the external reference to sum_n and displays this output:

$ cc -Aa main.c
/usr/ccs/bin/ld: Unsatisfied symbols:
   sum_n (code)

The crt0.o Startup File

The 64-bit linker uses the startup file, /opt/langtools/lib/pa_64/crt0.o, when:

The linker is in compatibility mode (+compat).

The linker is in default standard mode (+std) with the -noshared option.

If the linker option -I is specified to create an executable file with profile-based optimization, in 32-bit mode icrt0.o is used, and in 64-bit mode the linker inserts /usr/ccs/lib/pa20_64/fdp_init.o. If the linker options -I and -b are specified to create a shared library with profile-based optimization, in 32-bit mode scrt0.o is used, and in 64-bit mode, the linker inserts /usr/ccs/lib/pa20_64/fdp_init_sl.o. In 64-bit mode, the linker uses the single 64-bit crt0.o to support these option.

For details on startup files, see crt0(3).

The Program's Entry Point

In 64-bit mode for dynamically bound executables, the entry point, defined by the symbol $START$ in the dynamic loader (dld.sl).

The a.out File

Magic Numbers

SHARE_MAGIC

The program's text (code) can be shared by processes; its data cannot be shared. The first process to run the program loads the entire program into virtual memory. If the program is already loaded by another process, then a process shares the program text with the other process.

DEMAND_MAGIC

As with SHARE_MAGIC the program's text is shareable but its data is not. However, the program's text is loaded only as needed - that is, only as the pages are accessed. This can improve process startup time since the entire program does not need to be loaded; however, it can degrade performance throughout execution.

EXEC_MAGIC

Neither the program's text nor data is shareable. In other words, the program is an unshared executable. Usually, it is not desirable to create such unshared executables because they place greater demands on memory resources.

An executable file's magic number can also be changed using the chatr command (see Changing a Program's Attributes with chatr(1) ). However, chatr can only toggle between SHARE_MAGIC and DEMAND_MAGIC; it cannot be used to change from or to EXEC_MAGIC. This is because the file format of SHARE_MAGIC and DEMAND_MAGIC is exactly the same, while EXEC_MAGIC files have a different format. For details on magic numbers, refer to magic(4).

In 64-bit mode, the linker sets the magic number to the predefined type for ELF object files (\177ELF). The value of the E_TYPE in the ELF object file specifies how the file should be loaded.

File Permissions

$ umask
022
$ ls -l a.out
-rwxr-xr-x   1 michael  users      74440 Apr  4 14:38 a.out

Linking with Libraries

Library Naming Conventions

libname.suffix

name - is a string of one or more characters that identifies the library.

suffix - is .a if the library is an archive library or .sl if the library is a shared library. suffix is a number, for example .0, .1, and so forth, if library-level versioning is being used.

Default Libraries

$ cc -Aa -v main.c func.c
    ...
/usr/ccs/bin/ld /opt/langtools/lib/crt0.o -u main main.o \
func.o -lc
cc: Entering Link editor.

$ f77 -v sumnum.f
   ...
/usr/ccs/bin/ld -x /opt/langtools/lib/crt0.o \
 sumnum.o -lcl -lisamstub -lc

The Default Library Search Path

Link Order

Running the Program

Loading Programs: exec

Determine how to load the executable file by looking at its magic number. (See Also The a.out File .)

Determine where to begin execution of the program - that is, the entry point - usually in crt0.o. (See Also The crt0.o Startup File.)

When the program uses shared libraries, the crt0.o startup code invokes the dynamic loader (dld.sl), which in turn attaches any required shared libraries. If immediate binding was specified at link time, then the libraries are bound immediately. If deferred binding was specified, then libraries are bound as they are referenced. (See Also What are Shared Libraries?.)

Binding Routines to a Program

The dynamic loader binds only those symbols that are reachable during the execution of the program. This is similar to how archive libraries are treated by the linker; namely, ld pulls in an object file from an archive library only if the object file is needed for program execution.

Deferred Binding is the Default

Linker Thread-Safe Features

Also, beginning with the HP-UX 10.30 release, the linker toolset provides thread local storage support in:

ld - the link editor

dld.sl - the shared library dynamic loader

crt0.o - the program startup file

See your HP compiler documentation to learn how to create thread local storage data items with the _thread compiler directive.

See Programming with Threads on HP-UX for information on threads.

Pthread stubs in HP C library

Problem

Resolution

As per the libc cumulative patches, PHCO_22923 (11.00) and PHCO_23772 (11.11), t he libc shared library contains stubs for the pthread_* functions in libpthread and libcma. The stubs allow non-threaded applications to dynamically load threa d-safe libraries successfully, so that the pthread symbols are resolved. Applica tions that resolves pthread/cma calls to the stub must be built without -lpthread or -lcma on the link line.

Stubs provided in libc do not have any functionality, these are dummy functions returning zero except pthread_getspecific() family of APIs which has full functi onality implemented in the stubs.

List of pthread calls for which the stubs are provided in the C library is given below.

• pthread_atfork(3T)
• pthread_attr_destroy(3T)
• pthread_attr_getdetachstate(3T)
• pthread_attr_getguardsize(3T)
• pthread_attr_getinheritsched(3T)
• pthread_attr_getschedparam(3T)
• pthread_attr_getschedpolicy(3T)
• pthread_attr_getscope(3T)
• pthread_attr_getstackaddr(3T)
• pthread_attr_getstacksize(3T)
• pthread_attr_setdetachstate(3T)
• pthread_attr_setguardsize(3T)
• pthread_attr_setinheritsched(3T)
• pthread_attr_setschedparam(3T)
• pthread_attr_setschedpolicy(3T)
• pthread_attr_setscope(3T)
• pthread_attr_setstackaddr(3T)
• pthread_attr_setstacksize(3T)
• pthread_cancel(3T)
• pthread_cond_broadcast(3T)
• pthread_cond_destroy(3T)
• pthread_cond_init(3T)
• pthread_cond_signal(3T)
• pthread_cond_timedwait(3T)
• pthread_cond_wait(3T)
• pthread_condattr_destroy(3T)
• pthread_condattr_getpshared(3T)
• pthread_condattr_init(3T)
• pthread_condattr_setpshared(3T)
• pthread_continue(3T)
• pthread_detach(3T)
• pthread_getconcurrency(3T)
• pthread_getschedparam(3T)
• pthread_join(3T)
• pthread_kill(3T)
• pthread_mutex_destroy(3T)
• pthread_mutex_getprioceiling(3T)
• pthread_mutex_init(3T)
• pthread_mutex_lock(3T)
• pthread_mutex_setprioceiling(3T)
• pthread_mutex_trylock(3T)
• pthread_mutex_unlock(3T)
• pthread_mutexattr_destroy(3T)
• pthread_mutexattr_getprioceiling(3T)
• pthread_mutexattr_getprotocol(3T)
• pthread_mutexattr_getpshared(3T)
• pthread_mutexattr_gettype(3T)
• pthread_mutexattr_init(3T)
• pthread_mutexattr_setprioceiling(3T)
• pthread_mutexattr_setprotocol(3T)
• pthread_mutexattr_setpshared(3T)
• pthread_mutexattr_settype(3T)
• pthread_once(3T)
• pthread_rwlock_destroy(3T)
• pthread_rwlock_init(3T)
• pthread_rwlock_rdlock(3T)
• pthread_rwlock_tryrdlock(3T)
• pthread_rwlock_trywrlock(3T)
• pthread_rwlock_unlock(3T)
• pthread_rwlock_wrlock(3T)
• pthread_rwlockattr_destroy(3T)
• pthread_rwlockattr_getpshared(3T)
• pthread_rwlockattr_init(3T)
• pthread_rwlockattr_setpshared(3T)
• pthread_self(3T)
• pthread_setcancelstate(3T)
• pthread_setcanceltype(3T)
• pthread_setconcurrency(3T)
• pthread_setschedparam(3T)
• pthread_sigmask(3T)
• pthread_suspend(3T)
• pthread_testcancel(3T)

The pthread calls to any of the above stub returns zero.

Exceptions

The stub for the following pthread calls has full functionality. More informatio n about their functionalities is in the pthread (3T) man pages.

• pthread_key_create(3T)
• pthread_getspecific(3T)
• pthread_setspecific(3T)
• ptherad_key_delete(3T)
• pthread_exit(3T)

Calls to the stub,

• pthread_self(3T) always returns 1
• pthread_equal(arg1, arg2) returns (arg1 == arg2)
• pthread_create(3T) and pthread_attr_init(3T) returns ENOSYS.

Link Order problems:

An application may inadvertently pick up the stubs present in libc when it is in tended to use the real pthread APIs, or cma APIs. These are link order problems. An application that needs cma behavior must link to libcma and must do so in th e supported link order, i.e. the link line should only be shared and not contain -lc before -lcma.

So long as this condition is met, the correct cma functions will be referenced. Similarly, a multithreaded application that needs pthread library behavior must link to libpthread and must do so in a supported link order, and only use shared libc and libpthread.

Examples of Potential link order problems:

Example 1

The applications or any library linked that will resolve pthread/cma calls to th e stubs must be built without -lpthread or -lcma on the link line. If you specif y -lc before -lpthread, your application will use the pthread stubs in libc, but other problems may occur as given in the examples below:

$ cat thread.c
#include 
#include 

void *thread_nothing(void *p)
{
printf("Success\n");
}

int main()
{
    int err;
    pthread_t thrid;

    err = pthread_create(&thrid, (pthread_attr_t *) NULL, thread_nothing,
                         (void *) NULL);
    sleep(1);
    if (err) {
      printf("Error\n");
      return err;
    }
}

$ cc thread.c -lc -lpthread
$ a.out
Error

$ chatr a.out
a.out:
         shared executable
         shared library dynamic path search:
             SHLIB_PATH     disabled  second
             embedded path  disabled  first  Not Defined
         shared library list:
             dynamic   /usr/lib/libc.2  <- libc before libpthread
             dynamic   /usr/lib/libpthread.1
         shared library binding:
             deferred
         global hash table disabled

$ cc thread.c -lpthread
$ a.out
Success
$ chatr a.out

a.out:
         shared executable
         shared library dynamic path search:
             SHLIB_PATH     disabled  second
             embedded path  disabled  first  Not Defined
         shared library list:
             dynamic   /usr/lib/libpthread.1
             dynamic   /usr/lib/libc.2
         shared library binding:
             deferred
         global hash table disabled ...

Example 2

Specifying -lc before -lpthread in threaded applications can cause run-time prob lems as in the following example. Because the pthread/cma stubs are resolved ins tead of the real pthread/cma functions:

• calls to pthread functions fail, due to uninitialized internal structures
• calls to gethostbyname(3N) fail and return null
• Apache webmin and perl DBI applications fail with "Can't load '<libname.sl>' for module <xxx>: Invalid argument at <address>"
• calls to shl_load(3x) fail with errno 22 (invalid argument) because the pthre ad_mutex_lock stub returns zero

$ cat a.c
     #include 
     #include 

     extern int errno;

     main()
     {
             shl_load("/usr/lib/librt.2", BIND_DEFERRED, 0);
             printf("Error %d, %s\n", errno, strerror(errno));
     }

$ cc a.c -lc -lpthread
$ a.out
Error 22, Invalid argument
$ LD_PRELOAD=/usr/lib/libpthread.1 ./a.out
Error 0, Error 0

$ cat  b.c
     #include 
     #include 

     void* handle;
     extern int errno;

     main()
     {
             handle = dlopen("lib_not_found", RTLD_LAZY);
             printf("Error %d, %s\n", errno, strerror(errno));
             if (handle == NULL) {
               printf("Error: %s\n",dlerror());
             }
     }

$ cc b.c -lc -lpthread
$ a.out
Error 22, Invalid argument
Error:
$ LD_PRELOAD=/usr/lib/libpthread.1 ./a.out
Error 0, Error 0
Error: Can't open shared library: lib_not_found

Therefore, -lc should never be specified in the build command of an executable o r shared library.

By default, the compiler drivers (cc, aCC, f90) automatically pass -lc to the li nker at the end of the link line of the executables. It is not necessary to spec ify -lc when building a shared library because libc will be resolved by the refe rence to libc in the executable build command. The libc will be resolved by -lc that is automatically passed by the compiler drivers to the linker.

To see if a shared library was built with -lc, look at the shared library list i n the chatr() output, or list the dependent libraries with ldd(1):

$ cc +z -c lib1.c
$ ld -b -o lib1.sl lib1.o -lc
$ ldd lib1.sl
        /usr/lib/libc.2 =>      /usr/lib/libc.2
        /usr/lib/libdld.2 =>    /usr/lib/libdld.2
        /usr/lib/libc.2 =>      /usr/lib/libc.2

$ cc +DA2.0W +z -c lib1.c
$ ld -b -o lib1.sl lib1.o -lc
$ ldd lib1.sl
        libc.2 =>       /lib/pa20_64/libc.2
        libdl.1 =>      /usr/lib/pa20_64/libdl.1

To see the order in which dependent shared libraries will be loaded at run-time (order is only valid in 64-bit mode), use ldd(1) on the executable (ldd in 32-bi t mode displays the order in which libraries are loaded in reverse order):

$ cc +DA2.0W thread.c -lpthread
$ ldd a.out
        libpthread.1 => /usr/lib/pa20_64/libpthread.1
        libc.2 =>       /usr/lib/pa20_64/libc.2
        libdl.1 =>      /usr/lib/pa20_64/libdl.1
$ cc +DA2.0W thread.c -lc -lpthread
$ ldd a.out
        libc.2 =>       /usr/lib/pa20_64/libc.2
        libpthread.1 => /usr/lib/pa20_64/libpthread.1
        libdl.1 =>      /usr/lib/pa20_64/libdl.1
$ cc +DA2.0W thread.c -lpthread -lc
$ ldd a.out
        libpthread.1 => /usr/lib/pa20_64/libpthread.1
        libc.2 =>       /usr/lib/pa20_64/libc.2
        libdl.1 =>      /usr/lib/pa20_64/libdl.1

Recommendations:

• remove -lc from the build command of all shared libraries
• remove -lc from the build command of all executables
• use the LD_PRELOAD environment variable set to the full pathname for libpthread or libcma, which will cause the library to be loaded at program startup before other dependent libraries. LD_PRELOAD functionality is available in PHSS_22478 and later Linker patches. See the dld.sl(5) man page.
• if you link directly with ld(1) instead of with a compiler driver, add -lc as the last component on the link line.

Example 1 (64-bit):

If a 64-bit shared library is built with -lpthread but the executable is not, li bc is loaded before libpthread (due to breadth-first searching), and the pthread calls are resolved to the pthread stubs in libc. At run-time, after the a.out i s loaded, the dependencies of a.out are loaded in breadth-first order: libc is loaded as a dependent of a.out before libpthread is loaded as a dependent of libc.2. The dependency list of the first case is:

                     a.out
                  /     /   \
                lib1  lib2  libc
                  |     |
                libc  libpthread

  lib1.sl --> lib2.sl -->libc.2 --> libpthread.1

This is the desired behavior for non-threaded applications, but causes threaded applications (that use either libpthread or libcma) to fail.

# lib1.sl specifies -lc; lib2.sl specifies  -lpthread;
no -lpthread on a.out

$ cc -c +z +DA2.0W lib1.c lib2.c
lib1.c:
lib2.c:
$ ld -b -o lib1.sl -lc lib1.o
$ ld -b -o lib2.sl -lpthread lib2.o
$ cc +DA2.0W thread.c -L. -l1 -l2
$ a.out
Error
$ ldd a.out
        lib1.sl =>      ./lib1.sl
        lib2.sl =>      ./lib2.sl
        libc.2 =>       /usr/lib/pa20_64/libc.2
        libc.2 =>       /lib/pa20_64/libc.2
        libpthread.1 => /lib/pa20_64/libpthread.1
        libdl.1 =>      /usr/lib/pa20_64/libdl.1

# lib2.sl specifies -lpthread; no -lpthread on a.out
$ ld -b -o lib1.sl lib1.o
$ ld -b -o lib2.sl -lpthread lib2.o
$ cc +DA2.0W thread.c -L. -l1 -l2
$ a.out
Error
$ ldd a.out
        lib1.sl =>      ./lib1.sl
        lib2.sl =>      ./lib2.sl
        libc.2 =>       /usr/lib/pa20_64/libc.2
        libpthread.1 => /lib/pa20_64/libpthread.1
        libdl.1 =>      /usr/lib/pa20_64/libdl.1

The same problem will occur if -lcma is listed as a dependent library of a share d library, and you would need to link the executable with -lcma.

Solution:

For threaded applications, run the executable with LD_PRELOAD set to the libpthr ead library or link the executable with -lpthread:

# use LD_PRELOAD to load libpthread first
$ ld -b -o lib1.sl lib1.o
$ ld -b -o lib2.sl -lpthread lib2.o
$ cc +DA2.0W thread.c -L. -l1 -l2
$ a.out
Error
$ ldd a.out
        lib1.sl =>      ./lib1.sl
        lib2.sl =>      ./lib2.sl
        libc.2 =>       /usr/lib/pa20_64/libc.2
        libpthread.1 => /lib/pa20_64/libpthread.1
        libdl.1 =>      /usr/lib/pa20_64/libdl.1
$ LD_PRELOAD="/lib/pa20_64/libpthread.1" a.out
Success

# a.out correctly lists -lpthread for a threaded application
$ ld -b -o lib1.sl lib1.o
$ ld -b -o lib2.sl -lpthread lib2.o
$ cc +DA2.0W thread.c -L. -l1 -l2 -lpthread
$ a.out
Success
$ ldd a.out
        lib1.sl =>      ./lib1.sl
        lib2.sl =>      ./lib2.sl
        libpthread.1 => /usr/lib/pa20_64/libpthread.1
        libc.2 =>       /usr/lib/pa20_64/libc.2
        libpthread.1 => /lib/pa20_64/libpthread.1
        libdl.1 =>      /usr/lib/pa20_64/libdl.1

Example 2 (archived libc):

If the link line of your shared library contains -lc to explicitly link in libc, remove -lc. Otherwise, shared libraries may be referencing libc.2 while the a.out may reference some older (archived) libc version. Thus the application will actually be using two different versions of libc and possibly mixing code. This may cause compatibility problems. Basically, an application or library should ne ver directly link against libc. All programs need to be linked against libc (which the compiler does automatically), so a shared library will always have the interfaces it needs to execute properly without needing to specify -lc on the link line.

Linker Tasks

Using the Compiler Command
Changing the Default Library Search Path with -Wl, -L

Getting Verbose Output with -v

Passing Linker Options from the Compiler Command with -Wl

Renaming the Output File with -o

Specifying Libraries with -l

Suppressing the Link-Edit Phase with -c

Using the Linker Command
Linking with the 32-bit crt0.o Startup File

Changing the Default Library Search Path with -L and LPATH

Using $ORIGIN

Changing the Default Shared Library Binding with -B

Choosing Archive or Shared Libraries with -a

Dynamic Linking with -A and -R

Exporting Symbols with +e

Exporting Symbols from main with -E

Getting Verbose Output with -v

Hiding Symbols with -h

Improving Shared Library Performance with -B symbolic

Moving Libraries after Linking with +b

Moving Libraries After Linking with +s and SHLIB_PATH

Passing Linker Options from the Compiler Command with -Wl

Passing Linker Options in a file with -c

Passing Linker Options with LDOPTS

Specifying Libraries with -l and l:

Stripping Symbol Table Information from the Output File with -s and -x

Using the 64-bit mode linker command
Using the 64-bit Mode Linker with +compat or +std

Linking Shared Libraries with -dynamic

Linking Archived Libraries with -noshared

Controlling Archive Library Loading with +[no]forceload

Flagging Unsatisfied Symbols with +[no]allowunsats

Hiding Symbols from export with +hideallsymbols

Changing Mapfiles with -k and +nodefaultmap

Changing Mapfiles with -k and +nodefaultmap

Ignoring Dynamic Path Environment Variables with +noenvvar

Linking in 64-bit Mode with +std

Linking in 32-bit Mode Style with +compat

Controlling Output from the Unwind Table with +strip wind

Selecting Verbose Output with +vtype

Linking with the 64-bit crt0.o Startup File

Linker Compatibility Warnings

Using the Compiler to Link

Changing the Default Library Search Path with -Wl, -L

The -Llibpath option to ld augments the default search path; that is, it causes ld to search the specified libpath before the default places. The C compiler (cc), the C++ compiler (CC), the POSIX FORTRAN compiler (fort77), and the HP Fortran 90 compiler (f90) recognize the -L option and pass it directly to ld. However, the HP FORTRAN compiler (f77) and Pascal compiler (pc) do not recognize -L; it must be passed to ld with the -Wl option.

Example Using -Wl, -L

$f77 prog.f -Wl,-L,/usr/local/lib -llocal

(The f77 compiler searches /opt/fortran/lib and /usr/lib as default directories.)

To make the f90 compiler search /usr/local/lib to find a locally developed library named liblocal,, use this command line:

$f90 prog.f90 -L/usr/local/lib -llocal

(The f90 compiler searches /opt/fortran90/lib and /usr/lib as default directories.)

For the C compiler, use this command line:

$ cc -Aa prog.c -L /usr/local/lib -llocal

Getting Verbose Output with -v

$ pc -v prog.p
/opt/pascal/lbin/pascomp prog.p prog.o -O0
LPATH = /usr/lib/pa1.1:/usr/lib:/opt/langtools/lib
/usr/ccs/bin/ld /opt/langtools/lib/crt0.o -z prog.o -lcl -lm -lc
unlink prog.o

Passing Linker Options from the Compiler Command with -Wl

-Wl,arg1 [,arg2]...

where each argn is an option or argument passed to the linker. For example, to make ld use the archive version of a library instead of the shared, you must specify -a archive on the ld command line before the library.

Example Using -Wl

$ cc -Aa mathprog.c -Wl,-a,archive,-lm,-a,default

$ ld /opt/langtools/lib/crt0.o mathprog.o -a archive -lm \
  -a default -lc

Renaming the Output File with -o

$ cc -Aa -o sum_num prog.c           Compile using -o option.  
$ sum_num                            Run the program.                    
Enter a number to sum: 5
The sum of 1 to 5: 15

Specifying Libraries with -l

For example, if a C program calls library routines in the curses library (libcurses), you must specify -lcurses on the cc command line:

$ cc -Aa -v cursesprog.c -lcurses
    ...
/usr/ccs/bin/ld /opt/langtools/lib/crt0.o -u main \
 cursesprog.o -lcurses -lc
cc: Entering Link editor.

Linking with the crt0.o Startup File in 32-bit mode

Suppressing the Link-Edit Phase with -c

$ f77 -c func.f             Produce .o for func.f.         
$ ls func.o        
func.o                      Verify that func.o was created.
$ f77 main.f func.o         Compile main.f with func.o
$ a.out                     Run
it to verify it worked.

Using Linker commands

Linking with the 32-bit crt0.o Startup File

In 64-bit mode, you must include crt0.o on the link line for all fully archive links (ld -noshared) and in compatibility mode (+compat). You do not need to include the crt0.o startup file on the ld command line for shared bound links. In 64-bit mode, the dynamic loader, dld.sl, does some of the startup duties previously done by crt0.o.

See The crt0.o Startup File, and the crt0(3) man page for more information.

Changing the Default Library Search Path with -L and LPATH

Overriding the Default Linker Search Path with LPATH

If set, LPATH should contain a list of colon-separated directory path names ld should search. For example, to include /usr/local/lib in the search path after the default directories, set LPATH as follows:

$ LPATH=/usr/lib:/usr/local/lib     Korn and Bourne shell syntax.
$ export LPATH

Augmenting the Default Linker Search Path with -L

For example, suppose you have a locally developed version of libc, which resides in the directory /usr/local/lib. To make ld find this version of libc before the default libc, use the -L option as follows:

$ ld /opt/langtools/lib/crt0.o prog.o -L /usr/local/lib -lc

$ ld /opt/langtools/lib/crt0.o prog.o -L /usr/contrib/lib  \
-L /usr/local/lib -lc

Using $ORIGIN

To add $ORIGIN to the environment variables LD_LIBRARY_PATH or SHLIB_PATH, just place $ORIGIN in the value of these environment variables. To add $ORIGIN to the RUNPATH, use the linker options +b or -L. To add $ORIGIN to the path of a shared library in the shared library list, use the linker option +origin.

+origin -lx

+origin shared_library_name

$ ld main.o +origin libx.sl -L -lc

$ ld main.o -lc +b $ORIGIN

Changing the Default Shared Library Binding with -B

Example Using -B immediate

$ ld -B immediate /opt/langtools/lib/crt0.o prog.o -lc -lm

Nonfatal Shared Library Binding with -B nonfatal

To use nonfatal binding, specify the -B nonfatal option along with the -B immediate option on the linker command line. The order of the options is not important, nor is the placement of the options on the line. For example, the following ld command uses nonfatal immediate binding:

$ ld /opt/langtools/lib/crt0.o prog.o -B nonfatal \
  -B immediate -lm -lc

Restricted Shared Library Binding with -B restricted

The -B nonfatal modifier alters this behavior slightly: If the dynamic loader cannot find a symbol in the restricted set, it looks in the global symbol set (the symbols defined in all libraries) to resolve the symbol. If it still cannot find the symbol, then a run-time symbol-binding error occurs and the program aborts.

When is -B restricted most useful? Consider a program that creates duplicate symbol definitions by either of these methods:

The program uses shl_load with the BIND_FIRST flag to load a library that contains symbol definitions that are already defined in a library that was loaded at program startup.

The program calls shl_definesym to define a symbol that is already defined in a library that was loaded at program startup.

But what happens when, to take advantage of the performance benefits of deferred binding, the same program is linked with -B deferred? If a duplicate, more visible symbol definition is created prior to referencing the symbol, it binds to the more visible definition, and the program might run incorrectly. In such cases, -B restricted is useful, because symbols bind the same way as they do with -B immediate, but actual binding is still deferred.

Improving Shared Library Performance with -B symbolic

A benefit of -B symbolic is that it can help improve application performance and the resulting shared library will be slightly smaller. The -B symbolic option is useful for applications that make a lot of calls between procedures inside a shared library and when these same procedures are called by programs outside of the shared library.

Example Using -B symbolic

$ ld -B symbolic -b func1.o func2.o -o lib1.sl

Comparing -B symbolic with -h and +e

Case 1: Building a Shared Library with -B symbolic

Build the shared library with -b. Optimize the call path inside the shared library with -B symbolic.

$ ld -B symbolic -b convert.o volume.o -o libunits.sl

Two main programs link to the shared library. main1 calls convert_rtn() and main2 calls gal_to_liter().

$ cc -Aa main1.c libunits.sl -o main1
$ cc -Aa main1.c libunits.sl -o main2

Figure 4: Symbols inside a Shared Library Visible with -B symbolic

Case 2: Building a Shared Library with -h or +e

For example, you could hide the gal_to_liter symbol as shown:

$ ld -b convert.o -h gal_to_liter volume.o -o libunits.sl

$ ld -b +e convert_rtn convert.o volume.o -o libunits.sl

Figure 5: Symbol hidden in a Shared Library

Choosing Archive or Shared Libraries with -a

As an example, suppose you write an application that will run on a system on which shared libraries may not be present. Since the program could not run without the shared library, it would be best to link with the archive library, resulting in executable code that contains the required library routines. See also Caution When Mixing Shared and Archive Libraries .

Option Settings to -a

-a {archive | shared | default | archive_shared | shared_archive}

-a archive

Select archive libraries. If the archive library does not exist, ld generates an error message and does not generate the output file.

-a shared

Select shared libraries. If the shared library does not exist, ld generates an error message and does not generate the output file.

-a default

This is the same as -a shared_archive.

-a archive_shared

Select the archive library if it exists; otherwise, select the shared library. If the library cannot be found in either version, ld generates an error message and does not generate the output file.

-a shared_archive

Select the shared library if it exists; otherwise, select the archive library. If the library cannot be found in either version, ld generates an error message and does not generate the output file.

Example Using -a

$ ld /opt/langtools/lib/crt0.o prog.o -a archive -lcurses -lm -lc

Dynamic Linking with -A and -R

However, be aware that dynamic linking is incompatible with shared libraries. That is, a running program cannot be linked to shared libraries and also use ld -A to dynamically load object modules.

Topics in this section include:

Overview of Dynamic Linking describes steps to load an object file into a running program.

An Example Program provides an example dynamic linking scenario.

Overview of Dynamic Linking

Determine how much space is required to load the module.

Allocate the required memory and obtain its starting address.

Link the module from the running application.

Get information about the module's text, data, and bss segments from the module's header.

Read the text and data into the allocated space.

Clear (fill with zeros) the bss segment.

Flush the text from the data cache before executing code from the loaded module.

Get the addresses of routines and data that are referenced in the module.

Step 1: Determine how much space is required to load the module

Step 2: Allocate the required memory and obtain its starting address

Step 3: Link the module from the running application

-omod_name

Name of the output module that will be loaded by the running program.

-Abase_prog

Tells the linker to prepare the output file for incremental loading. Also causes the linker to include symbol table information from base_prog in the output file.

-Rhex_addr

Specifies the hexadecimal address at which the module will be loaded. This is the address calculated in Step 2.

-N

Causes the data segment to be placed immediately after the text segment.

-eentry_pt

If specified (it is optional), causes the symbol named entry_pt to be the entry point into the module. The location of the entry point is stored in the module's header.

Step 4: Get information about the module's text, data, and bss segments from the module's header

The useful members of the som_exec_auxhdr structure are:

.exec_tsize

Size of text (code) segment.

.exec_tmem

Address at which to load the text (already adjusted for offset specified by the -R linker option).

.exec_tfile

Offset into file (location) where text segment starts.

.exec_dsize

Size of data segment.

.exec_dmem

Address at which to load the data (already adjusted).

.exec_dfile

Offset into file (location) where data segment starts.

.exec_bsize

Size of bss segment. It is assumed to start immediately after the data segment.

.exec_entry

Address of entry point (if one was specified by the -e linker option).

Step 5: Read the text and data into the allocated space

The location of the text and data segments in the file is defined by the .exec_tfile and .exec_dfile members of the som_exec_auxhdr structure. The address at which to place the segments in the allocated memory is defined by the .exec_tmem and .exec_dmem members. The size of the segments to read in is defined by the .exec_tsize and .exec_dsize members.

Step 6: Clear (zero out) the bss segment

The end of the data segment can be determined by adding the .exec_dmem and .exec_dsize members of the som_exec_auxhdr structure. The bss's size is defined by the .exec_bsize member.

Step 7: Flush the text from the data cache before executing code from the loaded module

Use an assembly language routine named flush_cache (see The flush_cache Function in this chapter). You must assemble this routine separately (with the as command) and link it with the main program.

Step 8: Get the addresses of routines and data that are referenced in the module

If the module contains multiple routines and data that must be accessed from the main program, the main program can use the nlist(3C) function to get their addresses.

Another approach that can be used is to have the entry point routine return the addresses of required routines and data.

An Example Program

The program allocates space for dynobj.o by calling a function named alloc_load_space (see The alloc_load_space Function later in this chapter). The program then calls a function named dyn_load to dynamically link and load dynobj.o (see The dyn_load Function later in this chapter). Both functions are defined in a file called dynload.c (see dynload.c ).

As a return value, dyn_load provides the address of the entry point in dynobj.o - in this case, the function foo. To get the addresses of the function bar and the variable counter, the program uses the nlist(3C) function.

The Build Environment shows the example makefile used to create the dynprog program.

Source for dynprog shows the C source code for the dynprog program.

Output of dynprog shows the run time output of the dynprog program.

The flush_cache Function provides example source code in assembly language to flush text from the data cache.

The Build Environment

CFLAGS = -Aa -D_POSIX_SOURCE
dynprog:        dynprog.o dynload.o flush_cache.o
# Compile line:
  cc -o dynprog dynprog.o dynload.o flush_cache.o -Wl,-a,archive
 
file1.o:        file1.c dynprog.c
file2.o:        file2.c
 
# Create flush_cache.o:
flush_cache.o:
        as flush_cache.s

dynload.c

The file containing the alloc_load_space and dyn_load functions.

dynprog.c

The main program that calls functions from dynload.c and dynamically links and loads file1.o and file2.o. Also contains the function glorp, which is called by foo and bar.

file1.c

Contains the functions foo and bar.

file2.c

Contains the variable counter, which is incremented by foo, bar, and main.

flush_cache.s

Assembly language source for function flush_cache, which is called by the dyn_load function.

$ make dynprog file1.o file2.o 
        cc -Aa -D_POSIX_SOURCE -c dynprog.c
        cc -Aa -D_POSIX_SOURCE -c dynload.c
        cc -o dynprog dynprog.o dynload.o -Wl,-a,archive
        cc -Aa -D_POSIX_SOURCE -c file1.c
        cc -Aa -D_POSIX_SOURCE -c file2.c
        as -o flush_cache flush_cache.s

For details on using make refer to make(1).

Source for dynprog

#include <stdio.h>
#include <nlist.h>
 
extern void * alloc_load_space(const char * base_prog,
                               const char * obj_files,
                               const char * dest_file);
 
 
extern void * dyn_load(const char * base_prog,
                       unsigned int addr,
                       const char * obj_files,
                       const char * dest_file,
                       const char * entry_pt);
 
const char * base_prog = "dynprog";       /* this executable's name */
const char * obj_files = "file1.o file2.o"; /* .o files to combine  */
const char * dest_file = "dynobj.o";        /* .o file to load      */
const char * entry_pt  = "foo";             /* define entry pt name */
 
void glorp (const char *); /* prototype for local function          */
void (* foo_ptr) ();       /* pointer to entry point foo            */
void (* bar_ptr) ();       /* pointer to function bar               */
int * counter_ptr;         /* pointer to variable counter [file2.c] */
main()
{
  unsigned int addr;       /* address at which to load dynobj.o  */
  struct nlist nl[3];      /* nlist struct to retrieve addresse  */
 
/*
STEP 1:  Allocate space for module:
*/
 addr = (unsigned int) alloc_load_space(base_prog,
                                        obj_files, dest_file);
 
/*
STEP 2:  Load the file at the address, and get address of entry point:
*/
  foo_ptr = (void (*)()) dyn_load(base_prog, addr, obj_files,
                                  dest_file, entry_pt);
 
 
/*
STEP 3:  Get the addresses of all desired routines using nlist(3C):
*/
 
  nl[0].n_name = "bar";         
  nl[1].n_name = "counter";
  nl[2].n_name = NULL;
  if (nlist(dest_file, nl)) {
    fprintf(stderr, "error obtaining namelist for %s\n", dest_file);
    exit(1);
  }
  /*
   * Assign the addresses to meaningful variable names:
   */
  bar_ptr = (void (*)()) nl[0].n_value;
  counter_ptr = (int *) nl[1].n_value;
 
  /*
   * Now you can call the routines and modify the variables:
   */
  glorp("main");
  (*foo_ptr) ();
  (*bar_ptr) ();
  (*counter_ptr) ++;
  printf("counter = %d\n", *counter_ptr);
}
 
void    glorp(const char * from)
{
  printf("glorp called from %s\n", from);
}

file1.o and file2.o

/****************************************************************
 * file1.c - Contains routines foo() and bar().
 ****************************************************************/
 
extern int * counter_ptr;             /* defined in dynprog.c */
extern int counter;                   /* defined in file2.c   */
extern void glorp(const char * from); /* defined in dynprog.c */
 
void foo()
{
 glorp("foo");
 (*counter_ptr) ++; /* update counter indirectly with global pointer */
}
 
void bar()
{
 glorp("bar");
 counter ++;        /* update counter directly */
}
 
/****************************************************************
 * file2.c - Global counter variable referenced by dynprog.c 
 * and file1.c.
 ****************************************************************/
int counter = 0;

Output of dynprog

glorp called from main
glorp called from foo
glorp called from bar
counter = 3

dynload.c

#include <stdio.h>
#include <stdlib.h>
#include <nlist.h>
#  include <filehdr.h>           
#  include <aouthdr.h>           
#  define PAGE_SIZE 4096         /* memory page size  */

The alloc_load_space Function

void * alloc_load_space(const char * base_prog,
                        const char * obj_files,
                        const char * dest_file)

base_prog

The name of the program that is calling the routine. In other words, the name of the program that will dynamically link and load dest_file.

obj_files

The name of the object file or files that will be linked together to create dest_file.

dest_file

The name of the resulting object module that will be dynamically linked and loaded by base_prog.

The alloc_load_space function allocates only the required amount of space. To determine how much memory is required, alloc_load_space performs these steps:

Pre-link the specified obj_files to create base_prog.

Get text, data, and bss segment location and size information to determine how much space to allocate.

Return a pointer to the space. (The address of the space is adjusted to begin on a memory page boundary - that is, a 4096-byte boundary.)

void * alloc_load_space(const char * base_prog,
                        const char * obj_files,
                        const char * dest_file)
{
  char cmd_buf[256];    /* linker command line                   */
  int ret_val;          /* value returned by various lib calls   */
  size_t space;         /* size of space to allocate for module  */
  size_t addr;          /* address of allocated space            */
  size_t bss_size;      /* size of bss (uninitialized data)      */
  FILE * destfp;        /* file pointer for dest_file            */
  
  struct som_exec_auxhdr aux_hdr;       /* file header           */
  unsigned int tdb_size; /* size of text, data, and bss combined */
 
/* ---------------------------------------------------------------
 * STEP 1:  Pre-link the destination module so we can get its size:
 */
  sprintf(cmd_buf, "/bin/ld -a archive -R80000 -A %s -N %s -o %s -lc",
          base_prog, obj_files, dest_file);
  if (ret_val = system(cmd_buf)) {
    fprintf(stderr, "link failed: %s\n", cmd_buf);
    exit(ret_val);
  }
/* ---------------------------------------------------------------
 * STEP 2:  Get the size of the module's text, data, and bss segments 
 * from the auxiliary header for dest_file; add them together to 
 * determine size:
*/
  if ((destfp = fopen(dest_file, "r")) == NULL) {
    fprintf(stderr, "error opening %s\n", dest_file);
    exit(1);
  }
 
  /*
   * Must seek past SOM "header" to get to the desired 
   * "som_exec_auxhdr":
   */
  if (fseek(destfp, sizeof(struct header), 0)) {
    fprintf(stderr, "error seeking past header in %s\n", dest_file);
    exit(1);
  }
  if (fread(&aux_hdr, sizeof(aux_hdr), 1, destfp) <= 0) {
    fprintf(stderr, "error reading som aux header from %s\n", dest_file);
    exit(1);
  }
  
  /* allow for page-alignment of data segment */
  
  space = aux_hdr.exec_tsize + aux_hdr.exec_dsize 
    + aux_hdr.exec_bsize + 2 * PAGE_SIZE;    
 
  fclose(destfp);               /* done reading from module file */
/* ---------------------------------------------------------------
 * STEP 3:  Call malloc(3C) to allocate the required memory and get
 * its address; then return a pointer to the space:
 */
  addr = (size_t) malloc(space);
  /*
   * Make sure allocated area is on page-aligned address:
   */
  if (addr % PAGE_SIZE != 0) addr += PAGE_SIZE - (addr % PAGE_SIZE);
 
  return((void *) addr);
}

The dyn_load Function

void * dyn_load(const char * base_prog,
                unsigned int addr,
                const char * obj_files,
                const char * dest_file,
                const char * entry_pt)

To dynamically link and load dest_file into base_prog, the dyn_load function performs these steps:

Dynamically link base_prog with obj_files, producing dest_file. The address at which dest_file will be loaded into memory is specified with the -Raddr option. The name of the entry point for the file is specified with -eentry_pt.

Open dest_file and get its header information on the text, data, and bss segments. Read this information into a som_exec_auxhdr structure, which starts immediately after a header structure.

Read the text and data segments into the area allocated by alloc_load_space. (The text and data segments are read separately.)

Initialize (fill with zeros) the bss, which starts immediately after the data segment.

Flush text from the data cache before execution, using the flush_cache routine. (See The flush_cache Function later in this chapter.)

Return a pointer to the entry point, specified by the -e option in Step 1.

void * dyn_load(const char * base_prog,
                unsigned int addr,
 
                const char * obj_files,
                const char * dest_file,
                const char * entry_pt)
{
  char  cmd_buf[256];       /* buffer holding linker command       */
  int   ret_val;            /* holds return value of library calls */
  FILE  * destfp;           /* file pointer for destination file   */
  unsigned int bss_start;   /* start address of bss in VM          */
  unsigned int bss_size;    /* size of bss                         */
  unsigned int entry_pt_addr; /* address of entry point            */
 
  struct som_exec_auxhdr aux_hdr;  /* som file auxiliary header    */
  unsigned int tdb_size;    /* size of text, data, and bss combined*/
 
/* -----------------------------------------------------------------
 * STEP 1: Dynamically link the module to be loaded:
 */
  sprintf(cmd_buf, 
          "/bin/ld -a archive -A %s -R %x -N %s -o %s -lc -e %s",
          base_prog, addr, obj_files, dest_file, entry_pt);
          
  if (ret_val = system(cmd_buf)) 
  {
    fprintf(stderr, "link command failed: %s\n", cmd_buf);
    exit(ret_val);
  }
 
/* -----------------------------------------------------------------
 * STEP 2: Open dest_file. Read its auxiliary header for text, data, 
 *         and bss info:
 */
  if ((destfp = fopen(dest_file, "r")) == NULL) 
  {
    fprintf(stderr, "error opening %s for loading\n", dest_file);
    exit(1);
  }
 
  /*
   * Get auxiliary header information from "som_exec_auxhdr" struct, 
   * which is after SOM header.
   */
 
  if (fseek(destfp, sizeof(struct header), 0)) 
  {
    fprintf(stderr, "error seeking past header in %s\n", dest_file);
    exit(1);
  }
  
  if (fread(&aux_hdr, sizeof(aux_hdr), 1, destfp) <= 0) 
  {
    fprintf(stderr, "error reading som aux header from %s\n", dest_file);
    exit(1);
  }
/* -----------------------------------------------------------------
 * STEP 3:  Read the text and data segments into the buffer area:
 */
 
  /*
   * Read text and data separately.  First load the text:
   */
   
  if (fseek(destfp, aux_hdr.exec_tfile, 0)) 
  {
    fprintf(stderr, "error seeking start of text in %s\n", dest_file);
    exit(1);
  }
  
  if ((fread(aux_hdr.exec_tmem, aux_hdr.exec_tsize, 1, destfp)) <= 0)
  {
    fprintf(stderr, "error reading text from %s\n", dest_file);
    exit(1);
  }
  /*
   * Now load the data, if any:
   */
  if (aux_hdr.exec_dsize) {
    if (fseek(destfp, aux_hdr.exec_dfile, 0))
    {
      fprintf(stderr, "error seeking start of data in %s\n", dest_file);
      exit(1);
    }

 
    if ((fread(aux_hdr.exec_dmem, aux_hdr.exec_dsize, 1, destfp))<= 0)
    {
      fprintf(stderr, "error reading data from %s\n", dest_file);
      exit(1);
    }
  }
 
  fclose(destfp);               /* done reading from module file */
/* -----------------------------------------------------------------
 * STEP 4:  Zero out the bss (uninitialized data segment):
 */
 
  bss_start = aux_hdr.exec_dmem + aux_hdr.exec_dsize;
  bss_size  = aux_hdr.exec_bsize;
 
  memset(bss_start, 0, bss_size);
 
/* -----------------------------------------------------------------
 * STEP 5:  Flush the text from the data cache before execution:
 */
 
  /*
   * The flush_cache routine must know the exact size of the
   * text, data, and bss, computed as follows:
   *   Size = (Data Addr - Text Addr) + Data Size + BSS Size
   * where (Data Addr - Text Addr) = Text Size + alignment between
   *   Text and Data.
   */
  tdb_size = (aux_hdr.exec_dmem - aux_hdr.exec_tmem) +
    aux_hdr.exec_dsize + aux_hdr.exec_bsize;
  flush_cache(addr, tdb_size);
 
/* -----------------------------------------------------------------
 * STEP 6:  Return a pointer to the entry point specified by -e:
 */
 
  entry_pt_addr = (unsigned int) aux_hdr.exec_entry;
  return ((void *) entry_pt_addr);
}

The flush_cache Function

; flush_cache.s
;
; Routine to flush and synchronize data and instruction caches
; for dynamic loading
;
; Copyright Hewlett-Packard Co. 1985,1991, 1995
;
; All HP VARs and HP customers have a non-exclusive royalty-free 
; license to copy and use this flush_cashe() routine in source 
; code and/or object code. 
 
        .code
 
; flush_cache(addr, len) - executes FDC and FIC instructions for 
; every cache line in the text region given by starting addr and 
; len. When done, it executes a SYNC instruction and then enough 
; NOPs to assure the cache has been flushed.
;
; Assumption: Cache line size is at least 16 bytes.  Seven NOPs 
; is enough to assure cache has been flushed.  This routine is 
; called to flush the cache for just-loaded dynamically linked 
; code which will be executed from SR5 (data) space.
 
; %arg0=GR26, %arg1=GR25, %arg2=GR24, %arg3=GR23, %sr0=SR0.
; loop1 flushes data cache.  arg0 holds address.  arg1 holds offset.
; SR=0 means that SID of data area is used for fdc.
; loop2 flushes inst cache.  arg2 holds address.  arg3 holds offset.
; SR=sr0 means that SID of data area is used for fic.
; fdc x(0,y) -> 0 means use SID of data area.
; fic x(%sr0,y) -> SR0 means use SR0 SID (which is set to data area).
 
  .proc
  .callinfo
  .export flush_cache,entry
flush_cache
  .enter
  ldsid   (0,%arg0),%r1           ; Extract SID (SR5) from address
  mtsp    %r1,%sr0                ; SID -> SR0
  ldo     -1(%arg1),%arg1         ; offset = length -1
  copy    %arg0,%arg2             ; Copy address from GR26 to GR24
  copy    %arg1,%arg3             ; Copy offset from GR25 to GR23
 
  fdc     %arg1(0,%arg0)          ; Flush data cache @SID.address+offset
loop1
  addib,>,n     -16,%arg1,loop1   ; Decrement offset by cache line size
  fdc     %arg1(0,%arg0)          ; Flush data cache @SID.address+offset
  ; flush first word at addr, to handle arbitrary cache line boundary
  fdc     0(0,%arg0)
  sync
 
  fic     %arg3(%sr0,%arg2)       ; Flush inst cache @SID.address+offset
loop2
  addib,>,n       -16,%arg3,loop2 ; Decrement offset by cache line size
  fic     %arg3(%sr0,%arg2)       ; Flush inst cache @SID.address+offset
  ; flush first word at addr, to handle arbitrary cache line boundary
  fic     0(%sr0,%arg2)
 
  sync
  nop
  nop
  nop
  nop
  nop
  nop
  nop
  .leave
  .procend
  .end

Exporting Symbols with +e

The syntax of the +e option is:

+e symbol

Example Using +e

$ nm -p sem.o
0000000000 U  $global$
1073741824 d  $THIS_DATA$
1073741864 b  $THIS_BSS$
0000000004 cS sem_val
0000000000 T  check_sem_val
0000000036 T  foo
0000000000 U  printf
0000000088 T  bar
0000000140 T  sem

$ ld -b -h check_sem_val sem.o          One -h option.      
$ ld -b +e foo +e bar +e sem sem.o       Three +e options.

$ ld -b -h foo -h bar -h sem sem.o     Three -h options. 
$ ld -b +e check_sem_val sem.o                One +e option.

When to use -h versus +e

You should not combine -h and +e options on the same command line. For instance, suppose you specify +e sem. This would export the symbol sem and hide all other symbols. Any additional -h options would be unnecessary. If both -h and +e are used on the same symbol, the -h overrides the +e option.

The linker command line could get quite lengthy and difficult to read if several such options were specified. And in fact, you could exceed the maximum HP-UX command line length if you specify too many options. To get around this, use ld linker option files, described under Passing Linker Options in a file with -c . You can specify any number of -h or +e options in this file.

You can use -h or +e options when building a shared library (with -b) and when linking to create an a.out file. When combining .o files with -r, you can still use only the -h option.

Exporting Symbols with +ee

Exporting Symbols from main with -E

The +e option allows you to be more selective about which symbols are exported, resulting in better performance. For details on +e, see Exporting Symbols with +e.

Hiding Symbols with -h

You can use -h option when building a shared library (with -b) and when linking to create an a.out file. When combining .o files with -r, you can use the -h option.

The syntax of the -h option is:

-h symbol

The -h option hides symbol. Any other global symbols remain exported unless hidden with -h.

Example Using -h

$ nm -p sem.o
0000000000 U  $global$
1073741824 d  $THIS_DATA$
1073741864 b  $THIS_BSS$
0000000004 cS sem_val
0000000000 T  check_sem_val
0000000036 T  foo
0000000000 U  printf
0000000088 T  bar
0000000140 T  sem

$ ld -b -h check_sem_val sem.o

Tips on Using -h

The linker command line could get quite lengthy and difficult to read if several such options were specified. And in fact, you could exceed the maximum HP-UX command line length if you specify too many options. To get around this, use ld linker option files, described under Passing Linker Options in a file with -c . You can specify any number of -h or +e options in this file.

Hiding and Exporting Symbols When Building a Shared Library

It can improve performance because the dynamic loader does not have to bind hidden symbols. Since most symbols need not be exported from a shared library, hiding selected symbols can have a significant impact on performance.

It ensures that the definition can only be accessed by other routines in the same library. When linking with other object modules or libraries, the definition will be hidden from them.

When linking with other libraries (to create an executable), it ensures that the library will use the local definition of a routine rather than a definition that occurs earlier in the link order.

When using +e, be sure to export any data symbols defined in the shared library that will be used by another shared library or the program, even if these other files have definitions of the data symbols. Otherwise, your shared library will use its own private copy of the global data, and another library or the program file will not see any change.

One example of a data symbol that should almost always be exported from a shared library is errno. errno is defined in every shared library and program; if this definition is hidden, the value of errno will not be shared outside of the library.

Hiding Symbols When Combining .o Files with the -r Option

Hiding and Exporting Symbols When Creating an a.out File

$ ld /usr/ccs/lib/crt0.o prog.o -lm -lc

As mentioned previously in the section Exporting Symbols from main with -E , the -E option forces the export of all symbols from the program, regardless of whether they are referenced by shared libraries on the linker command line. The +e option allows you to be more selective in what symbols are exported. You can use +e to limit the exported symbols to only those symbols you want to be visible.

For example, the following ld command exports the symbols main and foo. The symbol main is referenced by libc. The symbol foo is referenced at run time by an explicitly loaded library not specified at link time:

$ ld /usr/ccs/lib/crt0.o prog.o +e main +e foo -lm -lc -ldld

One example of a data symbol that should almost always be exported from a program is errno. errno is defined in every shared library and program; if this definition is hidden, the value of errno will not be shared outside of the program in which it is hidden.

Moving Libraries after Linking with +b

Note that dynamic path list search works only for libraries specified with -l on the linker command line (for example, -lfoo). It won't work for libraries whose full path name is specified (for example, /usr/contrib/lib/libfoo.sl). However, it can be enabled for such libraries with the -l option to the chatr command (see Changing a Program's Attributes with chatr(1) ).

Specifying a Path List with +b

+b path_list

$ ld /opt/langtools/lib/crt0.o +b .:/app/lib:: prog.o -lfoo \
  -lm -lc

$ LPATH=/tmp ; export LPATH
$ ld /opt/langtools/lib/crt0.o +b : -L/app/lib prog.o -lfoo \
  -lm -lc

The Path List

Absolute and relative path names are allowed. Relative paths are searched relative to the program's current working directory at run time.

Remember that a shared library's full path name is stored in the executable. When searching for a library in an absolute or relative path at run time, the dynamic loader uses only the basename of the library path name stored in the executable. For instance, if a program is linked with /usr/local/lib/libfoo.sl, and the directory path list contains /apps/lib:xyz, the dynamic loader searches for /apps/lib/libfoo.sl, then ./xyz/libfoo.sl.

The full library path name stored in the executable is referred to as the default library path. To cause the dynamic loader to search for the library in the default location, use a null directory path (). When the loader comes to a null directory path, it uses the default shared library path stored in the executable. For instance, if the directory path list in the previous example were /apps/lib::xyz, the dynamic loader would search for /apps/lib/libfoo.sl, /usr/local/lib/libfoo.sl, then ./xyz/libfoo.sl.

If the dynamic loader cannot find a required library in any of the directories specified in the path list, it searches for the library in the default location () recorded by the linker.

Note that dynamic path list search works only for libraries specified with -l on the linker command line (for example, -lfoo). It won't work for libraries whose full path name is specified (for example, /usr/contrib/lib/libfoo.sl). However, it can be enabled for such libraries with the -l option to the chatr command (see Changing a Program's Attributes with chatr(1) ).

Moving Libraries After Linking with +s and SHLIB_PATH

Specifying a Path List with +s and SHLIB_PATH

For More Information:

The Path List provides additional details about the path list to SHLIB_PATH.

Moving Libraries after Linking with +b provides another way to move libraries.

Passing Linker Options in a file with -c

$ ld -o libmods.sl -b -c eopts mod*.o 
$ cat eopts       Display the file. 
+e foo
+e bar
+e reverse_tree
+e preorder_traversal
+e shift_reduce_parse
  .
  .
  .

# Exporting only the "compress" symbol resulted
# in better run-time performance:
+e compress
# When the program is debugged, remove the pound sign
# from the following optimization option:
# -O

Passing Linker Options with LDOPTS

$ LDOPTS="-v -t"    Korn and Bourne shell syntax. 
$ export LDOPTS

$ ld /opt/langtools/lib/crt0.o -u main prog.o -lc
$ ld -v -t /opt/langtools/lib/crt0.o -u main prog.o -lc

Specifying Libraries with -l and l:

Specifying Libraries (-l)

The x argument corresponds to the identifying portion of the library path name - the part following lib and preceding the suffix .a or .sl. For example, for the libm.sl or libm.a library, x is the letter m:

$ cc -Aa mathprog.c -lm

Using the -l: option

The advantage of using this option is that it allows you to specify an archive or shared library explicitly without having to change the state of the -a option. (See also Caution When Mixing Shared and Archive Libraries .)

For instance, suppose you use the LDOPTS environment variable (see Passing Linker Options with LDOPTS ) to set the -a option that you want to use by default when linking. And depending on what environment you are building an application for, you might set LDOPTS to -a archive or -a shared. You can use -l: to ensure that the linker will always link with a particular library regardless of the setting of the -a option in the LDOPTS variable.

Example Using -l:

$ ld /opt/langtools/lib/crt0.o -u main prog.o -L/usr/mylibs \
     -l:libfoo.a -l:libc.a -l:libm.a

Stripping Symbol Table Information from the Output File with -s and -x

-s

Strips all such information from the file. The executable becomes smaller, but difficult or impossible to use with a symbolic debugger. You can get much the same results by running the strip command on an executable (see strip(1)). In some cases, however, -s rearranges the file to save more space than strip.

-x

Strips only local symbols from the symbol table. It reduces executable file size with only a minimal affect on commands that work with executables. However, using this option may still make the file unusable by a symbolic debugger.

Using 64-bit Mode Linker Options

Using the 64-bit Mode Linker with +compat or +std

Compatibility mode, with the +compat option, to create a link and operation in 32-bit style. Because of some object file format restrictions, the mode is not completely compatible with the style of the 32-bit linker.

Standard mode, with the +std option, set by default in 64-bit mode, to create a link and load operation in 64-bit style. This mode uses the new behaviors and features of the 64-bit linker.

Using the Linker with +compat for Compatibility Mode

When you use the +compat option, the linker:

Uses 32-bit style shared library internal name processing.

Lists all dependent shared libraries in a DT_HP_NEEDED entry the dynamic table using the 32 bit-style shared library naming conventions. These dependent libraries are recorded as compatibility mode libraries even if they are really created as standard mode dependent libraries.

If an error occurs during the link, the linker creates an a.out without the executable permission bits set.

Does not use embedded paths at link time to find dependent libraries.

Considers the order of ld +b and +s.

+b first means dld looks at the RPATH first when searching for dependent shared libraries.

To get the default RPATH, you must specify ld +b. This instructs the linker to construct a default RPATH consisting of the -L directories and LPATH.

+s first means the dynamic loader looks at the SHLIB_PATH environment variable first when searching for dependent shared libraries.

You must specify ld +s to force the dynamic loader to use SHLIB_PATH to search for shared libraries at runtime.

Does dynamic path searching for compatibility-mode dependent shared libraries that have the dynamic path selected (set in the DT_HP_NEEDED entry if the shared library was specified with -l).

Uses SHLIB_PATH only if you specify ld +s (or chatr +s) for compatibility-mode shared libraries.

Allows RPATH inheritance from ancestors to children when searching for dependent compatibility-mode shared libraries specified with ld -l. This is only allowed in an a.out that was linked with +compat. If the a.out was linked +std, no library (even a compatibility mode shared library) uses embedded RPATH inheritance.

Allows dynamic path searching on shared libraries loaded by shl_load routines, if the DYNAMIC_FLAG is passed to shl_load().

Does a depth-first search of all compatibility-mode dependent libraries.

Looks at RPATH or SHLIB_PATH first, depending on the ld +b/+s ordering for all ld -l dependent shared libraries. The dynamic loader looks at whichever has second precedence next, and then looks for the shared library as specified in the dynamic load entry.

Looks for the dynamic table entry as if the dynamic path bit is not set.

Using the 64-bit Linker with +std for Standard Mode

This default may change in future releases.

When you use +std, the linker:

Assumes -dynamic was passed to ld. The linker looks for shared libraries first. The output executable is a shared executable.

All dependent shared libraries are output in the dynamic table in a DT_NEEDED entry. These dependent shared libraries are recorded as standard mode shared libraries.

ld +b and +s ordering is ignored. ld +s is on by default.

If an error occurs during the link, the linker does not generate an a.out file.

Uses de facto standard internal name processing for dependent shared libraries.

Uses embedded RPATHs at link time to find dependent shared libraries.

If you do not specify ld +b, the linker uses a default RPATH consisting of the -L directories, LPATH, and the default directories /usr/lib/pa20_64:/usr/ccs/lib/pa20_64.

Does dynamic path searching only for standard-mode shared libraries in the DT_NEEDED entry of the dynamic table which do not contain a path. For those standard-mode dynamic libraries that contain paths, dld looks for the library as specified.

Looks for the shared library as specified in the DT_NEEDED dynamic table entry if it contains a path.

Looks at LD_LIBRARY_PATH and SHLIB_PATH environment variables at runtime by default when doing dynamic path searching for standard-mode shared libraries.

Does not allow RPATH inheritance from ancestors to children (only allowed from parent to child).

Does a breadth-first search for all standard-mode dependent shared libraries.

Looks at the environment variables first, followed by RPATH, and the default directories by default when doing dynamic path searching for standard-mode dependentshared libraries.

Linking Shared Libraries with -dynamic

This option is on by default in standard mode.

In the following example, the linker only looks for shared libraries:

$ld main.o -dynamic -L. -lbar -lc

Linking Archived Libraries with -noshared

In the following example, the linker only looks for /usr/lib/pa20_64/libfoo.a and /usr/lib/pa20_64/libc.a:

ld crt0.o main.o -noshared -L. -lfoo -lc

ld: The shared library "libbar.sl" cannot be processed in a static link.
Fatal error.

Controlling Archive Library Loading with +[no]forceload

+noforceload is the default on both 32-bit and 64-bit modes.

In the following example, main() references foo(), which is a module in mylib.a. foo() doesn't reference any other module in mylib.a and libc.a. If mylib.a contains foo.o and bar.o, then only foo.o is linked in.

ld crt0.o main.o +vtype libraries mylib.a -lc

...
Selecting liba.a[foo.o] to resolve foo

ld crt0.o main.o +forceload mylib.a -lc +vtype libraries

...
Selecting liba.a[foo.o] to forcibly load
Selecting liba.a[bar.o] to forcibly load

Flagging Unsatisfied Symbols with +[no]allowunsats

Use the +noallowunsat option to instruct the linker to flag as an error any unsatisfied symbol in the resulting output file. The linker still creates a.out, but the file does not have any execute permission bits set. This is the default for program files (same behavior as in 32-bit mode).

For example, where main() references functions foo() and bar(). bar() resides in libbar.sl. foo() resides in libfoo.sl

ld main.o +allowunsats -L. -lbar -lc

ld: (warning) Unsatisfied symbol "foo".
1 warning.

ld main.o -L. -lbar -lc

ld: Unsatisfied symbol "foo".
1 error.

Hiding Symbols from export with +hideallsymbols

In the following example, main() exports func() and test(). Using +hideallsymbols, the linker does not export these two routines in the a.out.

ld main.o +hideallsymbols -L. -lfoo -lc

elfdump -t a.out

a.out:
 
...
.symtab
 
index   Type    Bind    Other   Sect    Value                   Size    Name
1       FUNC    LOCL    0       0xb     0x4000000000001104      0       test
 ...
10      FUNC    LOCL    0       0xb     0x4000000000001200      0       func

Changing Mapfiles with -k and +nodefaultmap

Use the -k filename option to provide a memory map. The linker uses the file specified by filename as the output file memory map.

The +nodefaultmap option used with -k option prevents the linker from concatenating the default memory map to the map provided by filename. If you specify +nodefaultmap, the linker does not append the default mapfile to your mapfile. If you do not specify +nodefaultmap with -k, the linker appends the output file to the default mapfile.

For more information on mapfiles and examples using these options, see Using Mapfiles.

Ignoring Dynamic Path Environment Variables with +noenvvar

For example, if libbar.sl has dependent library libfee.sl that is ./ at link time, but is moved to /tmp by runtime:

ld main.o -L. -lbar -lc
export LD_LIBRARY_PATH=/tmp
mv libbar.sl /tmp
a.out
        called bar() 
        called fee()
mv /tmp/libbar.sl ./
ld main.o +noenvvar -L. -lbar -lc
mv libbar.sl /tmp
a.out
        dld.sl: Unable to find library "libbar.sl"

Linking in 64-bit Mode with +std

Linking in 32-bit Mode Style with +compat

Controlling Output from the Unwind Table with +strip wind

ld -b foo.o -o libfoo.sl +stripunwind
elfdump -U libfoo.sl

libfoo.sl:

Selecting Verbose Output with +vtype

Parameter

Description

files

 

 
 
 
 
 
 
 
 
 
 
 
 
 

Dump information about each object file loaded.

ld main.o +vtype files -L. -lfile1 -lfile2 -lc
Loading main.o:
Loading ./libfile1.sl:
Loading ./libfile2.sl:
Loading /usr/lib/pa20_64/libc.2:

Loading /usr/lib/pa20_64/libdl.1:

libraries

 

 
 
 
 
 
 
 
 
 
 
 
 
 

Dump information about libraries searched.

ld main.o +vtype libraries -L. -lfile1 -lfile2 -lc
Searching /usr/lib/pa20_64/libc.a:
Selecting /usr/lib/pa20_64/libc.a[printf.o] to resolve printf
Selecting /usr/lib/pa20_64/libc.a[data.o] to resolve __iob
...

sections

 

 
 
 
 
 
 
 
 
 
 
 
 
 

Dump information about each section added to the output file.

ld main.o +vtype sections -L. -lfile1 -lfile2 -lc
main.o:
section .text PROG_BITS AX 116 8 added to text segment
section .PARISC.unwind UNWIND 16 4 added to text segment
section .data PROG_BITS AW 96 8 added to data segment

symbols

 

 
 
 
 
 
 
 
 
 
 
 
 
 

Dump information about global symbols referenced/defined from/in the input files.

ld main.o +vtype symbols -L. -lfile1 -lfile2 -lc
main.o:
        main is DEFINED GLOBAL FUNC
        printf is UNDEF GLOBAL FUNC
        lib1_func is UNDEF GLOBAL FUNC
        lib2_func is UNDEF GLOBAL FUNC
./libfile1.s:
        printf is UNDEF GLOBAL FUNC
        _DYNAMIC is DEFINED GLOBAL OBJECT
        lib1_func is DEFINED GLOBAL FUNC
        ...

heap

Dump information about heap

int main(int argc, char *argv[])
{
return 0;
}
!

cc -c +DA2.0W 1.c || exit 1

/usr/ccs/bin/ld /opt/langtools/lib/pa20_64/crt0.o +vtype heap 1.o -lc

===> results in

Heap: initial break value (heap begin) = 1654 KB
Heap: main entry break value = 1672 KB
Heap: before begin pass1 break value = 3808 KB
Heap: before pass1 break value = 4100 KB
Heap: before end pass1 break value = 6304 KB
Heap: end pass1 break value = 6368 KB
Heap: end pass2 break value = 6440 KB
Heap: main exit break value = 6440 KB, max heap usage = 4786 KB

all

 

 
 
 
 
 
 
 
 
 
 
 
 
 

Dump all of the above. Same as -v.

ld main.o +vtype all -L. -lfile1 -lfile2 -lc
Loading main.o:
main.o:
        main is DEFINED GLOBAL FUNC
        printf is UNDEF GLOBAL FUNC
        lib1_func is UNDEF GLOBAL FUNC
        lib2_func is UNDEF GLOBAL FUNC
main.o:section .text PROG_BITS AX 116 8 added to text segment
section .PARISC.unwind UNWIND 16 4 added to text segment
section .data PROG_BITS AW 96 8 added to data segment
Loading ./libfile1.sl:
./libfile1.sl:
...

Linking with the 64-bit crt0.o Startup File

In 64-bit mode, you must include crt0.o on the link line for all fully archive links (ld -noshared) and in compatibility mode (+compat). You do not need to include the crt0.o startup file on the ld command line for shared bound links. In 64-bit mode, the dynamic loader, dld.sl, does some of the startup duties previously done by crt0.o.

See The crt0.o Startup File, and crt0(3) manual page for more information.

Linker Compatibility Warnings

Link-time compatibility warnings include the following:

Linking PA-RISC 2.0 object files on any system - PA-RISC 1.0 programs run on 1.1 and 2.0 systems. PA-RISC 2.0 programs do not run on 1.1 or 1.0 systems. See Also PA-RISC Changes in Hardware Compatibility .

Dynamic linking with -A - If you do dynamic linking with -A, you should migrate to using the shared library management routines described in Shared Library Management Routines . These routines are also described in the sh_load(3X) and dl*(3X) man page.

The 64-bit mode linker does not support the -A option.

Procedure call parameter and return type checking (which can be specified with -C) - The 32-bit linker checks the number and types of parameters in procedure calls across object modules. In a future release, you should expect HP compilers to perform cross-module type checking, instead of the linker. This impacts HP Pascal and HP Fortran programs.

The 64-bit mode linker does not support the -C option.

Duplicate names found for code and data symbols - The 32-bit linker can create a program that has a code and data symbol with the same name. In the HP-UX 11.00 release, the 64-bit mode linker adopts a single name space for all symbols. This means that code and data symbols cannot share the same name. Renaming the conflicting symbols solves this problem.

Unsatisfied symbols found when linking to archive libraries - If you specify the -v option with the +vallcompatwarnings option and link to archive libraries, you may see new warnings. For an example, see Linking to Archive Libraries with Unsatisfied Symbols in this chapter.

Versioning within a shared library - If you do versioning within a shared library with the HP_SHLIB_VERSION (C and C++); or the SHLIB_VERSION (Fortran and Pascal) compiler directive, you should migrate to the industry standard and faster-performing library-level versioning. See Library-Level Versioning to learn how to do library-level versioning. In the HP-UX 11.00 release, the 64-bit mode linker does not support internal library versioning.

Linking to Archive Libraries with Unsatisfied Symbols

ld: (Warning) The file library.a(x.o) has not been fully
checked for unsatisfied symbols.  This behavior may
change in future releases.

For example, given these source files:

archive.c

int foo;        /* definition of uninitialized
                   global data symbol               */
void func()
{
     unsat();
}

extern int foo; /* declaration of global data symbol */
main()
{
     printf ("\tfoo = %d\n", foo);
}

cc -c main.c
cc -c archive.c
ar rv liba.a archive.o
ld /opt/langtools/lib/crt0.o -v \
  +vallcompatwarnings main.o liba.a -lc -o test

ld: (Warning) The file liba.a(archive.o) has not been fully
checked for unsatisfied symbols. This behavior may change
in future releases.

In the HP-UX 11.00 release, the linker includes the archive library object definition rather than fixing up the external reference.

Linker Tools

The following table lists the linker toolset.
 

Tool	Mode	Description
chatr	32-bit/64-bit	Displays or modifies the internal attributes of an object file. See Changing a Program's Attributes with chatr(1) .
elfdump	64-bit	Displays the contents of an ELF object file. See Viewing the Contents of an Object File with elfdump(1).
fastbind	32-bit/64-bit	Improves startup time of programs that use shared libraries. See Improving Program Start-up with fastbind(1).
ldd	32-bit/64-bit	Lists dynamic dependencies of executable files and shared libraries. Viewing library dependencies with ldd(1).
lorder	32-bit/64-bit	Finds ordering relationship for an object library. SeeFinding Object Library Ordering Relationships with lorder(1).
nm	32-bit/64-bit	Displays the symbol table of an object file. See Viewing Symbols in an Object file with nm(1) .
odump	32-bit	Displays the contents of a SOM object file. See the odump(1) man page.
size	32-bit/64-bit	Prints sizes of object file elements. See Viewing the Size of Object File Elements with size(1).
strip	32-bit/64-bit	Strips symbol and debugging information from an object file, executable, or archive library. See Reducing Storage Space with strip(1).

Changing a Program's Attributes with chatr(1)

Using chatr for 32-bit Program Attributes

Using chatr for 64-bit Program Attributes

Viewing Symbols in an Object file with nm(1)

nm provides three general output formats: the default (neither -p nor -P specified), -p, and -P. See the nm(1) man page for a detailed description of the output formats.
 

To	Use This Option
Prefix each output line with the name of the object file or archive, file. Equivalent to -r.	-A
64-bit mode ELF files only: Demangle C++ names before printing them.	-C
Display the value and size of a symbol in decimal. This is the default for the default format or the -p format. Equivalent to -t d.	-d
Display only external and static symbols. This option is ignored (see -f).	-e
Display full output. This option is in force by default.	-f
Display only external (global) symbol information.	-g
Do not display the output header data.	-h
Distinguish between weak and global symbols by appending * to the key letter of weak symbols. Only takes effect with -p and/or -P.	-l
Sort symbols by name, in ascending collation order, before they are printed. This is the default. To turn off this option, use -N.	-n
Display symbols in the order in which they appear in the symbol table.	-N
Display the value and size of a symbol in octal. Equivalent to -t o.	-o
Display information in a blank-separated output format. Each symbol name is preceded by its value (blanks if undefined) and one of the letters A absolute B bss symbol C common symbol D data symbol R section region S tstorage symbol (32-bit mode SOM files only) If the symbol is local (nonexternal), the type letter is in lowercase. If the symbol is a secondary definition, the type letter is followed by the letter S. Note that -p is not compatible with -P. T text symbol U undefined	-p
Display information in a portable output format as specified below, to standard output. Note that -p is not compatible with -P.	-P
32-bit mode SOM files only: Silence some warning messages.	-q
Prefix each output line with the name of the object file or archive, file. Equivalent to -A.	-r
64-bit mode ELF files only: Print the section index instead of the section name.	-s
Display each numeric value in the specified format. format can be one of: d Display the value and size of a symbol in decimal. This is the default for the default format or the -p format. Equivalent to -d. o Display the value and size of a symbol in octal. Equivalent to -o. x Display the value and size of a symbol in hexadecimal. This is the default for the -P format. Equivalent to -x.	-t format
32-bit mode SOM files only: Truncate every name that would otherwise overflow its column and place an asterisk as the last character in the displayed name to mark it as truncated. If -A or -r is also specified, the file prefix is truncated first. By default, nm prints the entire name of the symbols listed. Since object files can have symbol names with an arbitrary number of characters, a name that is longer than the width of the column set aside for names overflows its column, forcing every column after the name to be misaligned.	-T
Display undefined symbols only.	-u
Print the usage menu.	-U
Sort symbols by value before they are printed.	-v
Display the executing version of the nm command on standard error.	-V
Displays the value and size of a symbol in hexadecimal. this is the default for the -P format. Equivalent to -t x.	-x

Examples

Display which object files have undefined references for the symbol "leap":

"nm -rup *.o | grep leap"

Display which object files have a definition for the text symbol "leap":

nm -rp *.o | awk '{ if\ ($3 == " "T" " && $4 == " "leap" ") { print $0 } }'"

To view the symbols defined in an object file, use the nm command. The following 32-bit mode example shows output from running nm -p on the func.o and main.o object files.

$ nm -p func.o

                               Other symbols created from compiling.                     
1073741824 d  $THIS_DATA$
1073741824 d  $THIS_SHORTDATA$
1073741824 b  $THIS_BSS$
1073741824 d  $THIS_SHORTBSS$
0000000000 T  sum_n                 Global definitions of sum_n.
$ nm -p main.o
0000000000 U  $global$              Other symbols created from compiling.
1073741824 d  $THIS_DATA$
1073741872 d  $THIS_SHORTDATA$
1073741872 b  $THIS_BSS$
1073741872 d  $THIS_SHORTBSS$
0000000000 T  main                Global
definition of main.
0000000000 U  printf
0000000000 U  scanf
0000000000 U  sum_n

The first column shows the address of each symbol or reference. The last column shows the symbol name. The second column denotes the symbol's type:

T


indicates a global definition.

U


indicates an external reference.

d


indicates a local definition of data.

b


indicates a local definition of uninitialized data (bss).

Thus, a global definition of sum_n is found in func.o. An external reference to sum_n is found in main.o. External references to the C printf and scanf routines are found in main.o. For details on the use of nm, see nm(1).

Viewing the Contents of an Object File with elfdump(1)

The elfdump(1) command displays information contained in ELF format object files, archives, and shared libraries.

Use the following options to select the information you want to display:
 

To view the contents.	Use this option
Symbol table entries.	-t
Archive headers from an archive library.	-a
String table(s).	-c
File header.	-f
Global symbols from an archive.	-g
Section headers.	-h
The .dynamic section in shared libraries and dynamically linked program files.	-L
Optional headers (program headers).	-o
Relocations.	-r
Section contents.	-s
Unwind table.	-U

elfdump provides the following additional options to modify your selections:
 

Option	Modifies	Causes elfdump to
-H	all	Select output format in hexadecimal, octal, or decimal.
-p	all	Suppress title printing.
-S	-h,-o	Display headers in short format.
-C	-c, -r, -s, -t	Demangle C++ symbol names before displaying them.  With -H, ignored.  With -n name, display the symbol whose unmangled name matches name, and prints its symbol name as a demangled name.
-D num	-h, -s	Display the section whose index is num.
+Dnum2	-h, -s	Display the sections in the range 1 to num2. With -D, display the sections in the range num to num2.
-D num	-r	Display the relocation whose index is num.
+D num2	-r	Display only the relocations which apply to the section(s) in the range.
+s name	-c, -t	Display the section specified by name.
-n name	-h, -r, -s	Display information about the section specified by name.
-n name	-t	Display information about the symbol entry specified by name.
-T num	-t	Display the symbol whose index is num.
+T num2	-t	Display the symbols in the range 0 to num2. With-T, display the symbols in the range num to num2.

Viewing library dependencies with ldd(1)

Executable

All shared libraries that would be loaded as a result of executing the file.

Shared library

All shared libraries that would be loaded as a result of loading the library.

ldd does not list shared libraries explicitly loaded using dlopen(3C) or shl_load(3X).

ldd prints the record of shared library path names to stdout. It prints the optional list of symbol resolution problems to stderr.
 

To do this	Use the option
32-bit mode only. Used in conjuction with -d and/or -r, force dld.sl to bind all dependent libraries and report unsats. By default the smartbind mechanism in dld.sl only binds libraries whose symbols are explicitly referenced.	-b
Check reference to data symbols.	-d
Check reference to data and code symbols.	-r
Displays the search path used to locate the shared libraries.	-s
Display all dependency relationships.	-v

Examples

By default, ldd prints simple dynamic path information, including the dependencies recorded in the executable (or the shared library) followed by the physical location where the dynamic loader finds these libraries.

$ldd a.out

        ./libx.sl =>    ./libx.sl
        libc.2 =>       /lib/pa20_64/libc.2
        libdl.1 =>      /lib/pa20_64/libdl.1

The -v option causes ldd to print the dependency relationships along with the dynamic path information.

$ldd -v a.out

find library=./libx.sl; required by a.out 
        ./libx.sl =>    ./libx.sl 
find library=libc.2; required by a.out 
        libc.2 =>       /lib/pa20_64/libc.2
find library=libdl.1; required by /lib/pa20_64/libc.2
        libdl.1 =>      /lib/pa20_64/libdl.1

The -r option to causes it to analyze all symbol references and print information about unsatisfied code and data symbols.

$ldd -r a.out

./libx.sl       =>      ./libx.sl
libc.2  =>      /lib/pa20_64/libc.2
libdl.1 =>      /lib/pa20_64/libdl.1
symbol not found: val1 (./libx.sl)
symbol not found: count (./libx.sl)
symbol not found: func1 (./libx.sl)
symbol not found: func2 (./libx.sl)

Viewing the Size of Object File Elements with size(1)

Use the following options to display information for your specified files:
 

To display	Use this option
Sizes in decimal (default).	-d
Sizes in octal.	-o
Sizes in hexadecimal.	-x
Version information about the size command.	-V
Verbose list of the subspaces in the object files. Each subspace is listed on a separate line with its size, physical address, and virtual address.	-v
64-bit mode only: Size of each allocatable section.	-f
64-bit mode only: Size and permission bits of each loadable segment=.	-F
64-bit mode only: Sizes of non loadable segments or non allocatable sections.	-n

Reducing Storage Space with strip(1)

You can control the amount of information stripped from the symbol table by using the following options:
 

To	Use this option
Strip line number information only; do not strip any symbol table information.	-l
Do not strip static or external symbol information.	-x
32-bit mode only: Reset the relocation indexes into the symbol table. This option allows strip to be run on relocatable files, in which case the effect is also to strip only symbolic debugging information and unloadable data.	-r
Print the version of the strip command to stderr.	-V

If there are any relocation entries in the object file and any symbol table information is to be stripped, strip issues a message and terminates without stripping the specified file unless the -r option is used.

If you execute strip on an archive file (see ar(4)), it removes the archive symbol table. The archive symbol table must be restored by executing ar with its s operator (see ar(1)) before the ld command (see ld (1)) can use the archive. strip issues appropriate warning messages when this situation occurs.

Improving Program Start-up with fastbind(1)

fastbind performs analysis on the symbols used to bind an executable and all of its dependent shared libraries, and stores this information in the executable file. The next time the executable is run, the dynamic loader (/usr/lib/dld.sl for 32-bit mode or /usr/lib/pa20_64/dld.sl for 64-bit mode) detects that this information is available, and uses it to bind the executable instead of using the standard search method for binding the symbols.

Because fastbind writes the fastbind information in the executable file, you must have write permission on the executable file. If the executable file being analyzed is being run as another process or the file is locked against modifications by the kernel, the fastbind command fails.

If the shared libraries that an executable is dependent on are modified after the fastbind information is created, the dynamic loader silently reverts to standard search method for binding the symbols. The fastbind information can be re-created by running fastbind on the executable again. fastbind automatically erases the old fastbind information and generate the new one.
 

To do this	Use this option
Remove the fastbind information from the executable, returning it to the same state it as was in before you ran fastbind on it.	-n
Normally, if fastbind detects any unsatisfied symbols while building the fastbind information, it generates an error message and does not modify the executable file. When you invoke fastbind with the -u option however, it allows unresolved symbols.	-u

The 32-bit mode fastbind command does not work with EXEC_MAGIC executables.

fastbind effectively enforces the binding modes bind-restricted and bind-immediate. For example, consider an executable linked bind-deferred, which calls a function foo() defined in an implicitly loaded library. Before the actual call is made, if it explicitly loads a shared library (using shl_load(3X) with BIND_FIRST) having a definition for foo() when foo() is finally called, it is resolved from the explicitly-loaded library. But after running fastbind, the symbol foo() is resolved from the implicitly-loaded library.

For more information about fastbind and performance, see Improving Shared Library Start-Up Time with fastbind .
Example

To run fastbind on the executable file a.out:

$fastbind a.out

To later remove the fastbind information from the executable file a.out

$fastbind -n a.out

Finding Object Library Ordering Relationships with lorder(1)

You can process the output with tsort to find an ordering of a library suitable for one-pass access by ld (see tsort(1) and ld(1)). The linker ld is capable of multiple passes over an archive in the archive format and does not require that you use lorder when building an archive. Using the lorder command may, however, allow for a slightly more efficient access of the archive during the link-edit process.

The symbol table maintained by ar allows ld to randomly access symbols and files in the archive, making the use of lorder unnecessary when building archive libraries (see ar(1)).

lorder overlooks object files whose names do not end with .o, even when contained in library archives, and attributes their global symbols and references to some other file.
Examples

Build a new library from existing .o files:

$ar cr library `lorder *.o | tsort`

When creating libraries with so many objects that the shell cannot properly handle the *.o expansion, the following technique may prove useful:

$ls |grep '.o$'|lorder|tsort|xargs ar cq library

Creating and Using Libraries

General Information about Shared and Archive Libraries
Overview of Shared and Archive Libraries

What are Archive Libraries?

What are Shared Libraries?

Example Program Comparing Shared and Archive Libraries

Shared Libraries with Debuggers, Profilers, and Static Analysis

Creating Libraries on HP-UX
Creating Shared Libraries

Creating Archive Libraries

Using Libraries on HP-UX
Switching from Archive to Shared Libraries

Summary of HP-UX Libraries

Caution When Mixing Shared and Archive Libraries

Using Shared Libraries in 64-bit Mode
Internal Name Processing

Dynamic Path Searching for Shared Libraries

Shared Library Symbol Binding Semantics

Mixed Mode Shared Libraries

64-bit Mode Library Examples

Overview of Shared and Archive Libraries

Almost all system libraries are available both as a shared library and as an archive library for 32-bit mode in the directory /usr/lib and for 64-bit mode in /usr/lib/pa20_lib. Archive library file names end with .a whereas shared library file names end with .sl. For example, in 32-bit mode, the archive C library libc is /usr/lib/libc.a and the shared version is /usr/lib/libc.sl. In 64-bit mode, the archive C library libc is /usr/lib/pa20_64/libc.a and the shared version is /usr/lib/pa20_64/libc.sl

If both shared and archived versions of a library exist, ld uses the one that it finds first in the default library search path. If both versions exist in the same directory, ld uses the shared version. For example, compiling the C program prog.c causes cc to invoke the linker with a command like this:

For 32-bit mode: ld /opt/langtools/lib/crt0.o prog.o -lc

For 64-bit mode:

ld /opt/langtools/lib/pa20_64/crt0.o prog.o -lc

In addition to the system libraries provided on HP-UX, you can create your own archive and shared libraries. To create archive libraries, combine object files with the ar command, as described in Overview of Creating an Archive Library . To create shared libraries, use ld to combine object files containing position-independent code (PIC), as described in Creating Shared Libraries.

For more information, see Caution When Mixing Shared and Archive Libraries .

What are Archive Libraries?

Example

Figure 6: Linking with an Archive Library

What are Shared Libraries?

The Dynamic Loader dld.sl

Consequently, linking with shared libraries generally results in smaller a.out files than linking with archive libraries. Therefore, a clear benefit of using shared libraries is that it can reduce disk space and virtual memory requirements.

Default Behavior When Searching for Libraries at Run Time

$ ld /opt/langtools/lib/crt0.o prog.o -lc liblocal.sl

In 64-bit mode, the linker records ./liblocal.sl.

This is more of a concern with non-standard libraries-that is, libraries not found in /usr/lib or /usr/lib/pa20_64. There is little chance of the standard libraries not being in these directories.

Caution on Using Dynamic Library Searching

Example Program Comparing Shared and Archive Libraries

Figure 7: Two Processes Sharing libc

Compare this with the memory requirements if prog1 and prog2 had been linked with the archive version of libc. As shown in Figure 8: Two Processes with Their Own Copies of libc , 1428Kb of memory are required (768Kb + 640Kb). The numbers in this example are made up, but it is true in general that shared libraries reduce memory requirements.

Figure 8: Two Processes with Their Own Copies of libc

Shared Libraries with Debuggers, Profilers, and Static Analysis

Addition support is provided by the WDB Debugger. Refer to the WDB documentation at http://www.hp.com/go/wdb.

Profiling Shared Libraries with gprof(1)

Use the following steps to profile a shared library:

Set the environment variable LD_PROFILE to the shared library name.

Link the application which links with the library to be profiled to take one of the following actions:

Link with libc.sl.

Export all the symbols explicitly (with the ld +e option).

This is primarily for registration of the exit handler.

You can profile either the application or a shared library, however, you cannot profile both the application and the shared library together.

To profile applications, continue to use the existing gprof method, in which you compile with -G option, but do not set LD_PROFILE.

For example, to profile the shared library test.sl:

Set the environment variable LD_PROFILE to specify your shared library.

$LD_PROFILE=test.sl  
$export LD_PROFILE

If a.out is linked to test.sl, execute a.out.

$a.out

This step creates the file <shared_library>.profile (where shared_library is the name of the shared library specified by the LD_PROFILE environment variable) at run time. This file contains the profile information for the shared library. For this example, the file test.sl.profile is created.

To get the complete profile information about test.sl, run the gprof command:

$gprof test.sl test.sl.profile

Local, static, and hidden functions are not profiled.

Shared libraries built with -B symbolic are not profiled.

Any function calls made from library initializers are not collected.

Creating Archive Libraries

Compile one or more source files to create object files containing relocatable object code.

Combine these object files into a single archive library file with the ar command.

cc -Aa -c length.c volume.c mass.c
ar r libunits.a length.o volume.o mass.o

Other topics relevant to archive libraries are:

Contents of an Archive File

Example of Creating an Archive Library

Replacing, Adding, and Deleting an Object Module

Summary of Keys to the ar(1) Command

Archive Library Location

Overview of Creating an Archive Library

Create one or more object files containing relocatable object code. Typically, each object file contains one function, procedure, or data structure, but an object file could have multiple routines and data.

Combine these object files into a single archive library file with the ar command. Invoke ar with the r key.

("Keys" are like command line options, except that they do not require a preceding -.)

Figure 9: Creating an Archive Library

Contents of an Archive File

a header string, "!<arch>\n", identifying the file as an archive file created by ar (\n represents the newline character)

a symbol table, used by the linker and other commands to find the location, size, and other information for each routine or data item contained in the library

an optional string table used by the linker to store file names that are greater than 15 bytes long (only created if a long file name is encountered)

object modules, one for each object file specified on the ar command line

$ ar t /usr/lib/libm.a  
Run ar with the t key.

cosh.o                  
Object modules are displayed.

erf.o
fabs.o
floor.o
  . . . .

Example of Creating an Archive Library

length.c - Routine to Convert Length Units

float   in_to_cm(float in)  /* convert inches to centimeters */
{
  return (in * 2.54);
}

float   gal_to_l(float gal)  /* convert gallons to liters */
{
  return (gal * 3.79);
}

float   oz_to_g(float oz)    /* convert ounces to grams */
{
        return (oz * 28.35);
}

$ cc -Aa -c length.c volume.c mass.c     Compile them together.
length.c:
volume.c:
mass.c:
$ ls *.o                                  List the .o files.
length.o     mass.o      volume.o

$ ar r libunits.a length.o volume.o mass.o
ar: creating libunits.a

$ ar t libunits.a          Use ar with the t key.
length.o
volume.o
mass.o                    All the .o modules are included; it worked.

$ cc -Aa convert.c libunits.a

$ cc -Aa convert.c -lunits

Replacing, Adding, and Deleting an Object Module

Replacing or Adding an Object Module

$ ar r libunits.a length.o

Deleting an Object Module

$ ar d libunits.a volume.o        Delete volume.o. $ ar t libunits.a                 List the contents. length.o
mass.o                            volume.o is gone.

Summary of Keys to the ar(1) Command

ar [-] keys archive [modules] ...

Useful ar Keys

key

Description

d

Delete the modules from the archive.

r

Replace or add the modules to the archive. If archive exists, ar replaces modules specified on the command line. If archive does not exist, ar creates a new archive containing the modules.

t

Display a table of contents for the archive.

u

Used with the r, this modifier tells ar to replace only those modules with creation dates later than those in the archive.

v

Display verbose output.

x

Extracts object modules from the library. Extracted modules are placed in .o files in the current directory. Once an object module is extracted, you can use nm to view the symbols in the module.

$ ar tv libunits.a
rw-rr   265/    20    230 Feb  2 17:19 1990 length.o
rw-rr   265/    20    228 Feb  2 16:25 1990 mass.o
rw-rr   265/    20    230 Feb  2 16:24 1990 volume.o

$ ar ru libunits.a length.o

crt0.o

Users who link by letting the compilers such as cc invoke the linker do not have include crt0.o on the link line.

Archive Library Location

in the 32-bit /usr/lib or 64-bit /user/lib/pa20_64 directory

in the 32-bit /usr/local/lib or /usr/contrib/lib directory

Using /usr/lib and /usr/lib/pa20_64

The drawbacks of putting the libraries in /usr/lib or /usr/lib/pa20_64 are:

You usually need super-user (system administrator) privileges to write to the directory.

You could overwrite an HP-UX system library that resides in the directory.

Using /usr/local/lib or /usr/contrib/lib

Creating Shared Libraries

Creating Position-Independent Code (PIC) by compiling with +z.

Creating the Shared Library with ld by linking with -b.

$ cc -Aa -c +z length.c volume.c mass.c
$ ld -b -o libunits.sl length.o volume.o mass.o

Shared Library Dependencies

Updating a Shared Library

Version Control with Shared Libraries

Shared Library Location

Improving Shared Library Performance

Creating Position-Independent Code (PIC)

Compile source files with the +z or +Z compiler option, described below.

Write assembly language programs that use appropriate addressing modes, described in Position-Independent Code .

Example Using +z

$ cc -Aa -c +z length.c      The +z option creates PIC.

Comparing +z and +Z

In 64-bit mode, +Z is the default and the compilers ignore the options and generate PIC code.

Compiler Support for +z and +Z

In 64-bit mode, +Z is the default for the C and C++ compilers.

Creating the Shared Library with ld

For example, suppose you have three C source files containing routines to do length, volume, and mass unit conversions. They are named length.c, volume.c, and mass.c, respectively. To make a shared library from these source files, first compile all three files using the +z option, then combine the resulting .o files with ld. Shown below are the commands you would use to create a shared library named libunits.sl:

$ cc -Aa -c +z length.c volume.c mass.c
length.c:
volume.c:
mass.c:
$ ld -b -o libunits.sl length.o volume.o mass.o

$ chmod +r+x libunits.sl

$ cc -Aa convert.c libunits.sl

For details on linking shared libraries with your programs, see Linker Tasks.

Shared Library Dependencies

$ ld -b -o libdep.sl mod1.o mod2.o -lcurses -lcustom

There are two additional issues that may be important to some shared library developers:

When a shared library with dependencies is loaded, in what order are the dependent libraries loaded?

Where are all the dependent libraries placed in relation to other already loaded libraries? That is, where are they placed in the process's shared library search list used by the dynamic loader?

The Order in Which Libraries Are Loaded (Load Graph)

For example, suppose you create three libraries - libQ, libD, and libP - using the ld commands below. The order in which the libraries are built is important because a library must exist before you can specify it as a dependent library.

$ ld -b -o libQ.sl modq.o -lB
$ ld -b -o libD.sl modd.o -lQ -lB
$ ld -b -o libP.sl modp.o -lA -lD -lQ

libQ depends on libB

libD depends on libQ and libB

libP depends on libA, libD, and libQ

      +-->libA.sl
      |
libP.sl-->libD------+
      |    |        |
      |    v        v
      +-->libB.sl-->libQ.sl

For 32-bit mode

  if the library has not been visited then
      mark the library as visited.
      if the library has a dependency list then
          traverse the list in reverse order.
      Place the library at the head of the load list.

Shown below are the steps taken to form the load graph when libP is loaded:

mark P, traverse Q

mark Q, traverse B

mark B, load B

load Q

traverse D

mark D, traverse B

B is already marked, so skip B, traverse Q

Q is already marked, so skip Q

load D

mark A, load A

load P

  libP-->libA-->libD--> libQ--> libB

For 64-bit mode

  if the library has not been visited then
      mark the library as visited;
      append the library at the end of the list.
      if the library has a dependency list then
          traverse the list in order.

Shown below are the steps taken to form the load graph when libP is loaded:

mark P, load P

traverse P

mark A, loadA

mark D, loadD

mark Q, loadQ

traverse D

D is already marked, so skip D

traverse Q

Q is already marked, so skip Q

traverse Q

Q is already marked, so skip Q

traverse B

mark B, loadB

traverse B

B is already marked, so skip B

In standard dld-64 constructs the load graph in the following manner,

• Looks at the library name to be loaded
• Finds the dynamic path of the library for loading purposes or uses the absolute path referred and sees if the library to be loaded exists.
• If the library is not found, then dld searches for the library in the list of loaded libraries by comparing the basenames.
• If it does not find the library dld comes out with the standard error message saying that library could not be found.

Placing Loaded Libraries in the Search List

  <current search list>--> libP--> libA--> libD--> libQ--> libB

The same behavior occurs for libraries that are explicitly loaded with shl_load, but without the BIND_FIRST modifier (see BIND_FIRST Modifier for details). If BIND_FIRSTis specified in the shl_load call, then the libraries in the load graph are inserted before the existing search list. For example, suppose libP is loaded with this call:

lib_handle = shl_load("libP.sl", BIND_IMMEDIATE | BIND_FIRST, 0);

   libP--> libA--> libD--> libQ--> libB--><current search list>

Updating a Shared Library

$ cc -Aa -c +z length.c
$ ld -b -o libunits.sl length.o volume.o mass.o

This is one of the advantages of shared libraries over archive libraries: if you change an archive library, you must relink any programs that use the archive library. With shared libraries, you need only recreate the library.

Incompatible Changes to a Shared Library

Shared Library Location

Prior to the HP-UX 9.0 release, moving a shared library caused any programs that were linked with the library to fail when they tried to load the library. Prior to 9.0, you were required to relink all applications that used the library if the library was moved to a different directory.

Beginning with the HP-UX 9.0 release, a program can search a list of directories at run time for any required libraries. Thus, libraries can be moved after an application has been linked with them. To search for libraries at run time, a program must know which directories to search. There are two ways to specify this directory search information:

Store a directory path list in the program with the linker option +bpath_list.

Link the program with +s, enabling the program to use the path list defined by the SHLIB_PATH environment variable at run time.

For details on the use of these options, refer to Moving Libraries after Linking with +b and Moving Libraries After Linking with +s and SHLIB_PATH .

Improving Shared Library Performance

Loading Shared Libraries with the LD_PRELOAD Environment Variable

The LD_PRELOAD environment variable allows you to load additional shared libraries at program startup. LD_PRELOAD provides a colon- separated or space-separated list of shared libraries that the dynamic loader can interpret. The dynamic loader, dld.sl, loads the specified shared libraries as if the program had been linked explicitly with the shared libraries in LD_PRELOAD before any other dependents of the program.

At startup time, the dynamic loader implicitly loads one or more libraries, if found, specified in the LD_PRELOAD 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 following link line:

$ ld ... lib2.sl lib3.sl lib4.sl

If LD_PRELOAD="/var/tmp/lib1.sl", the dynamic loader uses the same load order and symbol resolution order as if lib1.sl had been specified as the first library in the link line:

$ ld ... /var/tmp/lib1.sl lib2.sl lib3.sl lib4.sl

In a typical command line use (with /bin/sh), where LD_PRELOAD is defined as follows:

$ LD_PRELOAD=mysl.sl application

The dynamic loader searches application according to $PATH, but searches mysl.sl according to SHLIB_PATH and/or LD_LIBRARY_PATH, and/or the embedded path (if enabled).

You can use the LD_PRELOAD environment variable to load a shared library that contains thread-local storage to avoid the following error when loading the library dynamically:

 /usr/lib/dld.sl: Can't shl_load() a library containing Thread Local Storage: /usr/lib/libpthread.1

The dynamic loader uses the LD_PRELOAD environment variable even if you use the +noenvvar in the link line. This insures that LD_PRELOAD is enabled even in a +compat link. The LD_PRELOAD variable is always enabled except for setuid and setgid programs.

Note: Using LD_PRELOAD can cause a core dump when used with applications which mix shared and archived libraries, especially when both the shared library and the application are built with aC++ or use libc.

You can specify multiple libraries as part of the LD_PRELOAD environment variable. Separate the libraries by spaces or colons as in LD_LIBRARY_PATH. (Multi-byte support is not provided as part of parsing the LD_PRELOAD library list). You can specify LD_PRELOAD libraries with absolute paths or relative paths. The LD_PRELOAD libraries can also consist of just the library names, in which case the dynamic loader uses the directory path list in the environment variables LD_LIBRARY_PATH and/or SHLIB_PATH 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 LD_PRELOAD. However, if it does not find a dependent of the LD_PRELOAD libraries, the dynamic loader issues the same error message as if the LD_PRELOAD library is specified in the link line.

LD_PRELOAD Example

                    a.out
                    /   \          
               libA.sl  libB.sl
                /  \          
          libC.sl  libD.sl

$ cc +DA2.0W -c +z ?.c 
$ ld -b -o libB.sl b.o 
$ ld -b -o libC.sl c.o 
$ ld -b -o libD.sl d.o 
$ ld -b -o libA.sl a.o -L. -lC -lD 
$ cc foo.c -L. -lA -lB

64-bit Behavior

$ ldd a.out 
    libA.sl =>       ./libA.sl
    libB.sl =>       ./libB.sl
    libc.2 =>        /usr/lib/pa20_64/libc.2
    libC.sl =>       ./libC.sl
    libD.sl =>       ./libD.sl
    libdl.1 =>       /usr/lib/pa20_64/libdl.1

a.out- -> libA.sl --> libB.sl --> libC.sl -->libD.sl
Case (i): LD_PRELOAD="./libB.sl"

In 64-bit mode, the symbol resolution order is:

$ export LD_PRELOAD="./libB.sl" 
$ ldd a.out
    ./libB.sl =>    ./libB.sl
    ./libB.sl =>    ./libB.sl
    libA.sl =>      ./libA.sl
    libB.sl =>      ./libB.sl
    libc.2 =>       /usr/lib/pa20_64/libc.2
    libC.sl =>      ./libC.sl
    libD.sl =       ./libD.sl
    libdl.1 =>      /usr/lib/pa20_64/libdl.1

In 64-bit mode, the symbol resolution order is:

$ export LD_PRELOAD="./libD.sl" 
$ ldd a.out
    ./libD.sl =>    ./libD.sl
    ./libD.sl =>    ./libD.sl
    libA.sl =>      ./libA.sl
    libB.sl =>      ./libB.sl
    libc.2 =>       /usr/lib/pa20_64/libc.2
    libC.sl =>      ./libC.sl
    libD.sl =>      ./libD.sl
    libdl.1 =>       /usr/lib/pa20_64/libdl.1

If the same symbol is defined in libA.sl and libD.sl, the 64-bit linker toolset uses the symbol defined in libD.sl since this library is loaded and searched before libA.sl when LD_PRELOAD="./libD.sl".

32-bit Behavior

mark B, load B

mark A, traverse D, load D

load C

load A

a.out --> libA.sl --> libC.sl --> libD.sl --> libB.sl
Case (i): LD_PRELOAD="./libB.sl"

In 32-bit mode, the dependents of a.out are treated as: libB.sl, libA.sl, libB.sl. The second libB.sl is ignored by the dynamic loader, since it is a duplicate library. So, the effective dependents of a.out are treated as: libB.sl, libA.sl. The load graph is:

mark A, traverse D, load D

load C

load A

load B

a.out --> libB.sl--> libA.sl --> libC.sl --> libD.sl
Case (ii): LD_PRELOAD = "./libD.sl"

In 32-bit mode, the load graph is:

mark B, load B

mark A, traverse D, load D

load C

load A

a.out --> libA.sl--> libC.sl --> libD.sl --> libB.sl

Using Profile-Based Optimization on Shared Libraries

Exporting Only the Required Symbols

One possible way to improve shared library performance is to export only those symbols that need exporting from a library. To control which symbols are exported, use either the +e or the -h option to the ld command. When +e options are specified, the linker exports only those symbols specified by +e options. The -h option causes the linker to hide the specified symbols. (For details on using these options, see Hiding Symbols with -h and Exporting Symbols with +e.)

As an example, suppose you've created a shared library that defines the procedures init_prog and quit_prog and the global variable prog_state. To ensure that only these symbols are exported from the library, specify these options when creating the library:

+e init_prog +e quit_prog +e prog_state

+e init_prog
+e quit_prog
+e prog_state

-c export_opts

Placing Frequently-Called Routines Together

a.o

Calls routines in c.o heavily, and its routines are called frequently by c.o.

b.o

 

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

A huge module, but contains only error routines that are seldom called.

c.o

 

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Contains routines that are called frequently by a.o, and calls routines in a.o frequently.

$ ld -b -o libabc.sl *.o

$ ld -b -o libabc.sl a.o c.o b.o

Another way is to use the lorder(1) and tsort(1) commands. Used together on a set of object modules, these commands determine how to order the modules so that the linker only needs a single pass to resolve references among the modules. A side-effect of this is that modules that call each other may be positioned closer together than modules that don't. For instance, suppose you have defined the following object modules:

Module

 

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Calls Routines in Module

a.o

x.oy.o

b.o

x.oy.o

d.o

none

e.o

none

x.o

d.o

y.o

d.o

$ lorder ?.o | tsort       Pipe lorder's output to tsort. a.o
b.o
e.o
x.o
y.o
d.o

a.o b.o x.o y.o d.o e.o

Making Shared Libraries Non-Writable

$ chmod 555 libname

Using the +ESlit Option to cc

To get around this, use the C compiler's +ESlit option, which places constant data in the $LIT$ text space (or in 64-bit mode, in a .text text segment) instead of the data space. This results in one copy of the constant data being shared among all processes that use the library.

Using filtered shared libraries

filter -  the library that exports a symbol, but does not contain implementation or storage for that symbol.

implementation -  the library that contains implementation and storage for a symbol.

The linker provides the +filter option, used with the -b option, to enable this mechanism.

$ld -b...+filter shared_library_pathname

If you divide a filtered shared library up into independent implementation libraries, the total memory consumption is reduced significantly if the application uses only a small portion of the library. This reduction is most significant when the shared library contains a large amount of static data which is not used by all applications.

It is important, when dividing a shared library into implementation libraries, that you keep them independent of each other. If there are dependencies between implementation libraries, the memory reduction benefits cannot be realized. Filtered shared libraries preserve compatibility because a filtered shared library appears as a single component to the application. You need to link only to the filter library, regardless of how many implementation libraries it is divided into.

Building filtered shared libraries

Build the independent implementation libraries which constitute a filter set. These implementation libraries contain the actual definitions of code and data symbols. Build these libraries like ordinary shared libraries using the -b linker option.

Build the filter library using the +filter linker option. Each implementation library which is part of the filter set is specified using the +filter option. For example:

$ld -b impl1.o -o libimpl1.sl 
$ld -b impl2.o -o libimpl2.sl 
$ld -b +filter libimpl1.sl +filter libimpl2.sl -o libfilt.sl

This builds a filtered shared library libfilt.sl with two implementation libraries libimpl1.sl and libimpl2.sl.

To confirm which implementation libraries are in the filter set, use odump to list the contents of the filter library:

$odump -filtertable libfilt.sl

Filtered Shared Library List Table for libfilt.sl:

            Index  String Table Offset  Name
 
            0                    11  ./libimpl1.sl
            1                    24  ./libimpl2.sl

The +filter option can be used in conjunction -L linker option or the LPATH environment variable. For example:

$ld -b -L. +filter impl1 +filter impl2 -o libfilt.sl

or

$export LPATH=. 
$ld -b -L. +filter impl1 +filter impl2 -o libfilt.sl

$ld -b a.o b.o...+filter libimpl1.sl +filter libimpl2.sl -o libfilt.sl

Building application programs linked to filtered shared libraries

$cc prog.c libfilt.sl -o prog

You can explicitly link your program with an implementation library, as well as with the parent filtered library, but you lose any advantage offered by the filter library feature. The implementation library is loaded as your program is run.

Run time behavior of filtered shared libraries

Initializers.

#include <dlfcn.h>
void initializer(void *handle, int loading)
{
        ...
        ptr = dlsym(handle, "symname");
        ...
}

Dynamic Path Lookup.

$ld -b impl1.o -o libimpl1.sl
$ld -b +b /path/to/implementation/libs +filter\ ./libimpl1.sl -o libfilt.sl
$chatr +b enable libfilt.sl
$cc prog.c libfilt.sl -o prog
$mv libimpl1.sl /path/to/implementation/libs
$./prog

Thread-private data (TLS).

Maintaining filtered shared libraries

Add or remove symbols from the set of exported symbols from the implementation libraries.

Change symbol types, for example, when an uninitialized data symbol (BSS symbol) is changed to an initialized data symbol (or vice-versa), or a text symbol into a data symbol.

Change the TLS (Thread Local Storage) size of an implementation library Even though the newly-added TLS symbols may not be exported outside the implementation library, you need to rebuild the filter library so the correct amount of TLS space is reserved.

To see the TLS size, use the following command:

$odump -sldlheader shared_library_pathname\ | fgrep tdsize

Version Control with Shared Libraries

When to Use Shared Library Versioning

Here are some guidelines to keep in mind when making changes to a library:

When creating the first version of a shared library, carefully consider whether or not you will need versioning. It is easier to use library-level versioning from the start.

When creating the first version of a shared library using intra-library versioning, version control is not an issue: The default version number is satisfactory.

When creating future revisions of a library, you must determine when a change represents an incompatible change, and thus deserves a new version. Some examples of incompatible changes are as follows:

As a general rule, when an exported function is changed such that calls to the function from previously compiled object files should not resolve to the new version, the change is incompatible. If the new version can be used as a wholesale replacement for the old version, the change is compatible.

For exported data, any change in either the initial value or the size represents an incompatible change.

Any function that is changed to take advantage of an incompatible change in another module should be considered incompatible.

Maintaining Old Versions of Library Modules

With library-level versioning, when an incompatible change is made to a module, the entire old version of the library must be retained along with the new version.

With intra-library versioning, when an incompatible change is made to a module, all the old versions of the module should be retained along with the new version. The new version number should correspond to the date the change was made. If several modules are changed incompatibly in a library, it is a good idea to give all modules the same version date.

Library-Level Versioning

How to Use Library-Level Versioning

Name the first version of your shared library with an extension of .0 (that's the number zero), for example libA.0. Use the +h option to designate the internal name of the library, for example, libA.0:

ld -b *.o -o libA.0 +h libA.0      Creates the shared library libA.0.

Since the linker still looks for libraries ending in .sl with the -l option, create a symbolic link from the usual name of the library ending in .sl to the actual library. For example, libA.sl points to libA.0:

ln -s libA.0 libA.sl                 libA.sl is a symbolic link to libA.0.

Link applications as usual, using the -l option to specify libraries. The linker searches for libA.sl, as usual. However, if the library it finds has an internal name, the linker places the internal name of the library in the executable's shared library dependency list. When you run the application, the dynamic loader loads the library named by this internal name. For example:

ld /opt/langtools/lib/crt0.o prog.o -lA -lc Binds a.out with libA.0.

Creating a New, Incompatible Version of the Library

Migrating an Existing Library to Use Library-Level Versioning

When you run a program that uses shared libraries and was linked before HP-UX 10.0, the dynamic loader first attempts to open the shared library ending in .0. If it cannot find that library, it attempts to open the library ending in .sl.

The +h Option and Internal Names

+h internal_name

You can include a relative or absolute path with the internal name, but you must ensure the dynamic loader can find the library from this name using its normal search process.

For 32-bit mode, if internal_name includes a relative path (that is, a path not starting with /), the internal name stored by the linker is the concatenation of the actual path where the library was found and internal_name, including the relative path. When the resulting program is run, if the dynamic loader cannot find the library at this location, the program will not run.

If internal_name includes an absolute path (that is, a path starting with /), the internal name stored by the linker is simply the internal_name, including the absolute path. When the resulting program is run, if the dynamic loader cannot find the library at this location, the program will not run.

For 64-bit mode, see Internal Name Processing for more information.

File System Links to Shared Libraries

$ ld -b -o /X/libapp.sl *.o          Create shared library.
$ ln -s /X/libapp.sl /tmp/libmine.sl Make the link.

Figure 10:

During a link, the linker records the file name of the opened library in the shared library list of the output file. However, if the shared library is a file system link to the actual library, the linker does not record the name of the library the file system link points to. Rather it records the name of the file system link.

For example, if /tmp/libmine.sl is a file system link to /X/libapp.sl, the following command records /tmp/libmine.sl in a.out, not /X/libapp.sl as might be expected:

$ ld /opt/langtools/lib/crt0.o main.o -L /tmp -lmine -lc

For example, in 32-bit mode, to make the above example work correctly with library-level versioning, first implement library-level versioning with the actual library /X/libapp.sl and include the absolute path in the internal name of the new library:

$ mv /X/libapp.sl /X/libapp.0               Rename old version.
$ ld -b -o /X/libapp.1 +h /X/libapp.1 *.o   Create new version.
$ ln -s /X/libapp.1  /X/libapp.sl           Set up symbolic link.

$ ln -s /X/libapp.0 /tmp/libmine.0    Link to old version.
$ ln -s /X/libapp.1 /tmp/libmine.1    Link to new version.
$ rm /tmp/libmine.sl                  Remove old link.
$ ln -s /X/libapp.sl /tmp/libmine.sl  Link to the link.

Figure 11:

With these links in place, the loader will load /X/libapp.0 when running the a.out file created above. New applications will link and run with /X/libapp.1.

For 64-bit mode programs, the dynamic loader only loads the library recorded in the dynamic load table. You should use library-lever versioning and create your 64-bit shared library with an internal name unless the library will not be versioned in the future.

Using shl_load(3X) with Library-Level Versioning

shl_load("libA.1", BIND_DEFERRED, 0);

Intra-Library Versioning

This section provides information on the following topics:

The Version Number Compiler Directive

Shared Library Dependencies and Version Control

Adding New Versions to a Shared Library

Specifying a Version Date

The Version Number Compiler Directive

C and C++:

#pragma HP_SHLIB_VERSION "date"

FORTRAN:

$SHLIB_VERSION 'date'

Pascal:

$SHLIB_VERSION 'date'$

This directive should only be used if incompatible changes are made to a source file. If a version number directive is not present in a source file, the version number of all symbols defined in the object module defaults to 1/90.

Shared Library Dependencies and Version Control

When a shared library is built with a dependent shared library, the version number of the dependent library used during the link is recorded with the dependency.

When shl_load(3X) is called to load a shared library, the latest version of the library is loaded. If that library has dependencies, the dynamic loader (dld.sl(5)) will load the versions of the dependent libraries that were recorded in the dependency list. Note that these are not necessarily the most recent versions of the dependent libraries. When dld.sl loads a particular version of a shared library, it will load the same version of any dependent libraries.

If a shared library lists a second shared library as a dependency, dld.sl will generate an error if the second shared library has a version number which is older than the version number recorded with the dependency. This means that the first library was built using a more recent version of the second library than the version that dld.sl currently finds.

Adding New Versions to a Shared Library

#pragma HP_SHLIB_VERSION "11/93" /* date is November 1993 */
/*
 * New version of "in_to_cm" also returns a character string
 * "cmstr" with the converted value in ASCII form.
 */
float   in_to_cm(float in, char *cmstr)     /* convert in to cm */
{
       . .  .         /* build "cmstr" */
        return(in * 2.54);
}
       . . .          /* other length conversion routines */

$ cp length.c oldlength.c              Save the old source.
$ mv length.o oldlength.o              Save old length.o.
         . . .                         Make new length.c.
$ cc -Aa -c +z length.c                Make
new length.o.
$ ld -b -o libunits.sl oldlength.o \   Relink the library.
    volume.o mass.o length.o

Specifying a Version Date

The reason for doing this is best illustrated with an example. Suppose in the previous example you gave each module a version date corresponding to the date it was completed: 04/93 for file1.o, 05/93 for file2.o, and 07/93 for file3.o. You then build the final library on 07/93 and link an application a.out with the library. Now suppose that you introduce an incompatible change to function foo found in file1.o, set the version date to 05/93, and rebuild the library. If you run a.out with the new version of the library, a.out will get the new, incompatible version of foo because its version date is still earlier than the date the application was linked with the original library!

Switching from Archive to Shared Libraries

Library Path Names

For 64-bit naming, see Internal Name Processing for more information.

Relying on Undocumented Linker Behavior

For example, suppose several definitions and references of a symbol exist in different object and archive library files. By specifying the files in a particular link order, you could cause the linker to use one definition over another. But doing so requires an understanding of the subtle (and undocumented) symbol resolution rules used by the linker, and these rules are slightly different for shared libraries. So make files or shell scripts that took advantage of such linker behavior prior to the support of shared libraries may not work as expected with shared libraries.

More commonly, programmers may take advantage of undocumented linker behavior to minimize the size of routines copied into the a.out files from archive libraries. This is no longer necessary if all libraries are shared.

Although it is impossible to characterize the new resolution rules exactly, the following rules always apply:

If a symbol is defined in two shared libraries, the definition used at run time is the one that appeared first, regardless of where the reference was.

The linker treats shared libraries more like object files.

Absolute Virtual Addresses

An example of an implicit address dependency is a function that assumes that two global variables that were defined adjacently in the source code will actually be adjacent in virtual memory. Since the linker may rearrange data in shared libraries, this is no longer guaranteed. Another example is a function that assumes variables it declares statically (for example, C static variables) reside below the reserved symbol _end in memory (see end(3)). In general, it is a bad idea to depend on the relative addresses of global variables, because the linker may move them around.

In assembly language, using the address of a label to calculate the size of the immediately preceding data structure is not affected: the assemblers still calculate the size correctly.

Stack Usage

Also be aware that if a program sets its stack pointer to memory allocated in the heap, the dynamic loader may use the space directly "above" the top of this stack when deferred binding of symbols is used.

Version Control

Debugger Limitations

Using the chroot Command with Shared Libraries

Conversely, if you move a program that uses shared libraries into a chrooted environment, you must have a copy of the dynamic loader, dld.sl, and all required shared libraries in the correct locations.

Profiling Limitations

Summary of HP-UX Libraries

HP-UX library routines are described in detail in sections 2 and 3 of the HP-UX Reference. Routines in section 2 are known as system calls, because they provide low-level system services; they are found in libc. Routines in section 3 are other "higher-level" library routines and are found in several different libraries including libc.

Each library routine, or group of library routines, is documented on a man page. Man pages are sorted alphabetically by routine name and have the general form routine(nL), where:

routine

is the name of the routine, or group of closely related routines, being documented.

n

is the HP-UX Reference section number: 2 for system calls, 3 for other library routines.

L

is a letter designating the library in which the routine is stored.

The major library groups defined in the HP-UX Reference are shown below:

Group

Description

(2)

These functions are known as system calls. They provide low-level access to operating system services, such as opening files, setting up signal handlers, and process control. These routines are located in libc.

(3C)

These are standard C library routines located in libc.

(3E)

These functions constitute the ELF access library (libelf) which lets a program manipulate ELF (Executable and Linking Format) object files, archive files, and archive members. The linker searches this library if the -lelf option is specified. The header file <libelf.h> provides type and function declarations for all library services (described in elf(3E).

(3S)

These functions comprise the Standard input/output routines (see stdio(3S)). They are located in libc.

(3M)

These functions comprise the Math library. The linker searches this library under the -lm option (for the SVID math library) or the -lM option (for the POSIX math library).

(3G)

These functions comprise the Graphics library.

(3I)

These functions comprise the Instrument support library.

(3X)

Various specialized libraries. The names of the libraries in which these routines reside are documented on the man page.

For more information on these libraries, see C, A Reference Manual by Samual P. Harbison and Guy L. Steele Jr., published in 1991 by Prentice-Hall, or UNIX System V Libraries by Baird Peterson, published in 1992 by Van Nostrand Reinhold, or C Programming for UNIX by John Valley, published in 1992 by Sams Publishing. For more information on system calls see Advanced UNIX Programming by Marc J. Rochkind, published in 1985 by Prentice-Hall or Advanced Programming in the UNIX Environment by W. Richard Stevens, published in 1992 by Addison-Wesley.

Caution When Mixing Shared and Archive Libraries

Mixing shared and archive libraries can lead to unsatisfied symbols, hidden definitions, and duplicate definitions and cause an application to abort or exhibit incorrect behavior at run time. The following examples illustrate some of these problems.

Example 1: Unsatisfied Symbols

$ cc -c main.c f1.c f2.c     Compile to relocatable object code.
$ cc -c +z f3.c              Compile to position-independent code

Figure 12:

Next suppose you put f3.o into the shared library lib3.sl and f1.o and f2.o into the archive library lib12.a:

$ ld -b -o lib3.sl f3.o     Create a shared library.
$ ar qvc lib12.a f1.o f2.o  Create an archive library.

Figure 13:

Now link the main with the libraries and create the executable a.out:

$ cc main.o lib12.a lib3.sl    Link the program .

Figure 14:

When you run a.out, it runs correctly. Now suppose you need to modify f3() to call f2():

Figure 15:

Compile the new f3() and rebuild the shared library lib3.sl:

$ cc -c +z f3.c           Compile to relocatable code.
$ ld -b -o lib3.sl f3.o    Create a new shared library

Figure 16:

Problem

Figure 17:

$ a.out
/usr/lib/dld.sl: Unresolved symbol: f2 (code) from
                 /users/steve/dev/lib3.sl
Abort(coredump)

Example 2: Using shl_load(3X)

If a library being loaded depends on a definition that does not exist in the application or any of the dependent shared libraries, the application will abort with an unsatisfied definition at run time. This seems obvious enough when an application is first created. However, over time, as the shared libraries evolve, new symbol imports may be introduced that were not originally anticipated. This problem can be avoided by ensuring that shared libraries maintain accurate dependency lists.

Suppose you have a main program, main(), and three functions, f1(), f2(), and f3() each in a separate source file. main() calls f1() and uses shl_load() to call f3(). main() does not call f2():

$ cc -c main.c f1.c f2.c    Compile to relocatable object code
$ cc -c +z f3.c           Compile to position-independent code

Figure 18:

Next suppose you put f3.o into the shared library lib3.sl and f1.o and f2.o into the archive library lib12.a:

$ ld -b -o lib3.sl f3.o     Create a shared library.
$ ar qvc lib12.a f1.o f2.o  Create an archive library.

Figure 19:

Now link the main with the archive library and create the executable a.out:

$ cc main.o lib12.a -ldld      Link the program.

Figure 20:

When you run a.out, it runs correctly. Now suppose you need to modify f3() to call f2():

Figure 21:

Problem

$ cc -c +z f3.c             Compile to position-independent code.
$ ld -b -o lib3.sl f3.o     Error! Missing library containing f2().

Figure 22:

Here's where the problem shows up. If you do not relink the application, main.o, and just run a.out with the new version of lib3.sl, the program will abort since f2() is not available in the program's address space. The reference to f2() from f3() remains unsatisfied, generating the 32-bit error message:

Figure 23:

$ a.out
Illegal instruction (coredump)

Example 3: Hidden Definitions

Duplicate definitions can occur when a dependent shared library is updated to refer to a symbol contained in the program file but not visible to the shared library. The new symbol import must be satisfied somehow by either adding the symbol to the library or by updating the shared library dependency list. Otherwise the application must be relinked.

Using an archive version of libc in an application using shared libraries is the most common cause of duplicate definitions. Remember that symbols not referenced by a shared library at link time will not be exported by default.

The following example illustrates this situation. Suppose you have a main program, main(), and three functions, f1(), f2(), and f3() each in a separate source file. main() calls f1(), f2(), and f3().

$ cc -c main.c               Compile to relocatable code.
$ cc -c +z f1.c f2.c f3.c    Compile to position-independent code.

Figure 24:

Next suppose you put f3.o into the shared library lib3.sl and f1.o and f2.o into the archive library lib12.a. Also put f1.o and f2.o into the shared library lib12.sl:

$ ld -b -o lib3.sl f3.o        Create a shared library.
$ ld -b -o lib12.sl f1.o f2.o  Create a shared library.
$ ar qvc lib12.a f1.o f2.o     Create an archive library.

Figure 25:

Now link the main with the archive library lib12.a and the shared library lib3.sl and create the executable a.out:

$ cc main.o lib12.a lib3.sl    Link the program.

Figure 26:

When you run a.out, it runs correctly. Now suppose you need to modify f3() to call f2():

Figure 27:

Compile the new f3() and rebuild the shared library lib3.sl, including the new dependency on f2() in lib12.sl:

$ cc -c +z f3.c                     Compile to PIC.

$ ld -b -o lib3.sl f3.o -L . -l12   Create library with dependency.

Figure 28:

Problem

Figure 29:

Example 4: Hidden Definitions - static variables

$ CC -G -c main.c                  Compile to relocatable object code
$ CC -c +z sub.c                   Compile to position-independent code

$ CC -b sub.o +z -o lib1.sl -lc    Create a shared library
$ CC -G main.o -L. -l1             Create an executable with profiling

Problem:

When the program is run, one set of static variables is modified. When the program is exited, the other set of static variables is read. Since the second set of static variables was never modified, no gmon.out file is created.

To avoid this problem, do not build shared libraries with libc.sl as a dependent library.  Besides libc.sl, the following libraries should not be included on the link line when building a shared library because these libraries contain thread-local storage: libcl.sl, libcma.sl, libpthread.sl (ie, -lcl -lcma -lpthread). Either include these libraries on the a.out link line (so the symbols needed for various runtime libraries are exported), or link the a.out with the -E linker option.

Summary of Mixing Shared and Archive Libraries

Providers of shared libraries should make every effort to prevent these kinds of problems. In particular, if a shared library provider allows unsatisfied symbols to be satisfied by an archive version of libc, the application that uses the library may fail if the shared library is later updated and any new libc dependencies are introduced. New dependencies in shared libraries can be satisfied by maintaining accurate dependency lists. However, this can lead to multiple occurrences of the same definition in an application if the definitions are not explicitly exported.

Using Shared Libraries in 64-bit mode

The 64-bit mode linker toolset introduces different types of shared libraries. (In SVR4 Unix, shared libraries are sometimes called dlls.)

Compatibility mode shared library: Using the 64-bit mode linker, a compatibility mode shared library is basically a library built with ld -b +compat that has dependent shared libraries. The +compat option affects the way the linker and loader search for dependent libraries of a shared library and records their names.

Standard mode shared library: A standard mode shared library is a library built with ld -b or ld -b +std with dependent shared libraries.

The linker handles these libraries in different way with regard to internal naming and library search modes.

Internal Name Processing

In an ld +compat link, the linker treats the internal names like it does in 32-bit mode:

If the dependent library's internal name is rooted (starts with "/"), it is inserted as is in the DT_HP_NEEDED entry. If it was specified with -l, the dynamic path bit is set to TRUE in the DT_HP_NEEDED entry.

If the dependent library's internal name contains a relative path, the internal name is inserted at the end of the path where the shared library is found at link time, replacing the library's filename in the DT_HP_NEEDED entry. If the library is specified with -l, the dynamic path bit is set to TRUE.

If the dependent library's internal name contains no path, it is inserted at the end of the path where the shared library is found at link time, replacing the library's filename. If the library is specified with -l, the dynamic path bit is set to TRUE.

If the dependent shared library does not have an internal name, the path where the library is found and the library filename is recorded in the DT_HP_NEEDED entry. If specified with -l, the dynamic path bit is set to TRUE.

If the shared libraries are specified with a relative or no path in this mode, the linker expands the current working directory when constructing the DT_HP_NEEDED entry. So instead of getting something like ./libdk.sl, you get /home/your_dir/libdk.sl.

All DT_HP_NEEDED entries with the dynamic path bit set are subject to dynamic path lookup.

If the dependent shared library has an internal name, it is recorded in the DT_NEEDED entry.

If the dependent shared library is specified with the -l or -l: option, only the libname.ext is recorded in the DT_NEEDED entry.

The path of the dependent shared library as seen on the link line is recorded in the DT_NEEDED entry.

All DT_NEEDED entries with no "/" in the libname are subject to dynamic path lookup.

Dynamic Path Searching for Shared Libraries

In the 32-bit mode of the linker toolset (selected by the +compat option), the linker enables run-time dynamic path searching when you link a program with the -llibrary and +b path_name options. Or, you can use the -llibrary option with the +spath_name option. When programs are linked with +s, the dynamic loader searches directories specified by the SHLIB_PATH environment variable to find shared libraries.

The following example shows dynamic path searching changes for 64-bit mode.

ld /opt/langtools/lib/crt0.o main.o \ Subject to 
 -lfoo -o main                        dynamic path searching.

Rules to determine the dynamic path list

• If ld +noenvvar was specified and ld +b and ld +compat were not specified, then the only dynamic path searching that can be done is to look at the path list in rpath followed by the default directories /usr/lib/pa20_64 and /usr/ccs/lib/pa20_64.
• If ld +compat was specified and ld +b and ld +s were not specified, no shared library is subject to dynamic path searching.
• If the ld +compat and ld +b options are not specified, then the path_list in the LD_LIBRARY_PATH environment variable is searched, followed by the path_list in the SHLIB_PATH environment variable, followed by the path_list in rpath, followed by the default directories /usr/lib/pa20_64 and /usr/ccs/lib/pa20_64.
• If the ld +compat, ld +b, and ld +s are specified, then use the relative ordering of ld +b and ld +s to determine if the dynamic loader should use the path_list in rpath before SHLIB_PATH followed by the library as specified in the shared library list. If ld +b is specified first, use the path_list in rpath first.

• For standard mode libraries, the path_list in the LD_LIBRARY_PATH environment variable is searched first, followed by the path_list in the SHLIB_PATH environment variable, followed by the value in the parent shared library's rpath, followed by the default directories /usr/lib/pa20_64 and /usr/ccs/lib/pa20_64.  The ancestors of a parent shared library may contain a path_list in rpath, but this is ignored when searching for dependent shared libraries of this parent.  Only the parent's rpath 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 parent shared libraries, except rpath can be passed from parent shared libraries to child dependent shared libraries to that child's dependents, et cetera.

Shared Library Symbol Binding Semantics

This section covers the following topics:

Link-time symbol resolution in shared libraries

Resolution of unsatisfied shared library references

Promotion of uninitialized global variables

Symbol searching in dependent libraries

Link-Time Symbol Resolution in Shared Libraries

The 32-bit mode linker does not remember the definition of a procedure in a shared library unless it was referenced in previously scanned object files.

If you have function names that are duplicated in a shared and archive library, the 64-bit mode linker may reference a different version of a procedure than is referenced by the 32-bit mode linker. This change can lead to unexpected results.

For example, given these source files:

sharedlib.c

    void afunc()
    {
        printf("\tin SHARED library procedure 'afunc'\n");
    }

    void bfunc()
    {
         afunc();
    }

    void afunc()
    {
        printf ("\tin ARCHIVE library procedure 'afunc'\n");
    }

    main()
    {
        bfunc();
    }

cc -c main.c unsat.c archive.c
cc -c +z sharedlib.c
ld -b sharedlib.o -o libA.sl
ar rv libB.a archive.o
cc main.o libA.sl unsat.o libB.a -o test1

$ test1
 
        in ARCHIVE library procedure `afunc'

The 64-bit mode linker toolset produces:

$ test1
 
        in SHARED library procedure `afunc'

Resolution of Unsatisfied Shared Library References

The 32-bit mode linker toolset accepts unresolved symbols in some cases. For example, if an entry point defined in an object file is never reachable from the main program file, the unresolved symbol is allowed. You can use the +vshlibunsats linker option to find unresolved symbols in shared libraries.

For example, given these source files:

lib1.c

    void a()
    {
    }

    extern int unsat;
    void b()
    {
        unsat = 14;
    }

    main()
    {
        a();
    }

cc -c main.c
cc -c +z lib1.c lib2.c
ld -b lib1.o lib2.o -o liba.sl
cc main.o liba.sl -o test2

The 64-bit mode linker toolset reports an unsatisfied symbol error for unsat at link time or at run time if the program were made executable.

Promotion of Uninitialized Global Data Items

The result of this change is that load-time symbol resolution for one of these objects stops at the first one encountered, instead of continuing through all loaded libraries to see if an initialized data object exists.

For example, given these source files:

a.c

    int object;    /* Uninitialized global data symbol */
    void a()
    {
        printf ("\tobject is %d\n", object);
    }

    int object =1; /* Initialized global data symbol */
    void b()
    {
    
    }

    main()
    {
    a();
    }

cc -c main.c
cc -c +z a.c b.c
ld -b a.o -o libA.sl
ld -b b.o -o libB.sl
cc main.o libA.sl libB.sl -o test3

$ test3
        object is 1

The 64-bit mode linker toolset produces:

$ test 3
        object is 0

Symbol Searching in Dependent Libraries

The 32-bit mode linker toolset searches dependent libraries in a depth-first order. This means it searches dependent shared library files in the order in which they are linked to shared libraries. The shl_load library management routines and executable files (a.out) created by the linker with the +compat option use the depth-first search order.

Figure 30: Search Order of Dependent Libraries shows an example program with shared libraries (the shaded boxes are libA.sl dependent libraries; and the example does not consider libDK or libLH) and compares the two search methods:

Figure 30: Search Order of Dependent Libraries

The commands to build the libraries and the executable in Figure 30: Search Order of Dependent Libraries are shown below. Note the link order of libraries in steps 2 and 3:

First, the dependent shared libraries for libA are built. (Other libraries are also built.)

ld -b libD.o -o libD.sl  libA dependent shared library
ld -b libE.o -o libE.sl  libA dependent shared library
ld -b libF.o -o libF.sl  libA dependent shared library
ld -b libB.o -o libB.sl
ld -b libC.o -o libC.sl

Next, libA.o is linked to its dependent libraries and libA.sl is built.

ld -b libA.o -lD -lE -lF -o libA.sl

Finally, main.o is linked to its shared libraries.

cc main.o -lA -lB -lC -o main

If you use mixed mode shared libraries, the search mechanism may produce unexpected results.

For the following command, libA.sl and its dependent libB.sl are compatibility mode libraries and libC.sl and libD.sl are standard mode libraries.

ld -b libF.o +compat -L.-lA -lC -o LibF.sl

libF.sl is a compatibility mode library, but is dependent libC.sl is a standard mode library. The linker uses depth-first searching mechanisms because the highest-level library is in compatability mode.

Mixed Mode Shared Libraries

If you use mixed mode shared libraries, you get behavior based on the first mode encountered. At runtime, the dynamic loader does a depth-first search if the dependent libraries at the highest level are compatibility mode libraries. Otherwise, it does breadth-first searching. This applies to all dependent libraries of the incomplete executable file. The loader cannot toggle back and forth between depth-first and breadth-first at the library level, so the first dependent library it sees determines which search method to use.

For example:

# build standard mode dlls
# libfile1.sl is a dependent of libfile2.sl
 
ld -b file1.o -o libfile1.sl +h libfile1.1
ld -b file2.o -o libfile2.sl +h libfile2.1 -L. -lfile1
 
# build compatibility mode dlls
# libfile3.sl is a dependent of libfile4.sl
 
ld -b file3.o -o libfile3.sl +h libfile3.1
ld -b file4.o -o libfile4.sl +h libfile4.1 -L. -lfile3 +compat
ln -s libfile1.sl libfile1.1
ln -s libfile3.sl libfile3.1
 
# build a dll using both standard and compatibility mode dependent dlls
# since we didn't specify +compat, the resulting dll is a standard mode dll
 
ld -b file5.o -o libfile5.sl +h libfile5.1 -L. -lfile4 -lfile2
ln -s libfile4.sl libfile4.1
ln -s libfile2.sl libfile2.1
ld main.o -L. -lfile5 -lc

64-bit Mode Library Examples

Library Example: Creating a 64-bit Mode Compatibility Mode Shared Library.

ld -b file1.o -o libfile1.sl +h libfile1.1
ld -b file2.o -o libfile2.sl +h ./libfile2.1
ld -b file3.o -o libfile3.sl +h /var/tmp/libfile3.1
ld -b file4.o -o libfile4.sl 
ld -b +compat file3a.o -o libfile3a.sl -L. -lfile -lfile3 +h libfile3a.1
ld -b +compat file2a.o -o libfile2a.sl libfile2.sl ./libfile4.sl +b /var/tmp
elfdump -L libfile3a.sl libfile2a.sl

libfile3a.sl:

        *** Dynamic Section ***

Index   Tag     Value
0       HPNeeded        1:./libfile1.1 
1       HPNeeded        1:/var/tmp/libfile3.1 
2       Soname  libfile3a.1
...

libfile2a.sl:

        *** Dynamic Section ***

Index   Tag     Value
0       HPNeeded        0:/home/knish/./libfile2.1 
1       HPNeeded        0:./libfile4.sl 
2       Rpath   /var/tmp
...

Library Example: Creating a 64-bit Standard Mode Shared Library

ld -b file1.o -o libfile1.sl +h libfile1.1
ld -b file2.o -o libfile2.sl +h ./libfile2.1
ld -b file3.o -o libfile3.sl +h /var/tmp/libfile3.1
ld -b file4.o -o libfile4.sl 
ld -b file3a.o -o libfile3a.sl -L. -lfile1 -lfile3 +h libfile3a.1
ld -b file2a.o -o libfile2a.sl libfile2.sl ./libfile4.sl +b /var/tmp
elfdump -L libfile3a.sl libfile2a.sl

libfile3a.sl:

        *** Dynamic Section ***

Index   Tag     Value/Ptr0      Needed  libfile1.1 
1       Needed  /var/tmp/libfile3.1
2       Soname  libfile3a.1
3       Rpath   .
...

libfile2a.sl:

        *** Dynamic Section ***

Index   Tag     Value/Ptr0      Needed  ./libfile2.1 
1       Needed  ./libfile4.sl 
2       Rpath   /var/tmp
...

Library example: 64-bit Mode Dynamic Path Searching

        # build standard mode shared libraries
        #libfile1.sl is a dependent of libfile2.sl
        ld -b file1.o -o libfile1.sl +h libfile1.1
        ld -b file2.o -o libfile2.sl +h libfile2.1 -L. -lfile1
        ld main.o -L. -lfile2 -lc       # move dependent lib so dld can't find it
        # dld won't find library because we didn't set the environment
# variable LD_LIBRARY_PATH and SHLIB_PATH
        # By default, dld will look at the environment variables
# LD_LIBRARY_PATH and
        # SHLIB_PATH when doing dynamic path searching unless +noenvvar 
# is specified
 
        mv libfile2.sl /var/tmp
        ln -s /var/tmp/libfile2.sl /var/tmp/libfile2.1
        a.out
        dld.sl: Unable to find library 'libfile2.1'
        export SHLIB_PATH=/var/tmp
        a.out
        in file1
        in file2

Library Example: 64-bit Mode Compatibility Mode Link

        # build compatibility mode dlls
        # libfile1.sl is a dependent of libfile2.sl
 
        ld -b file1.o -o libfile1.sl +h libfile1.1
        ld -b file2.o -o libfile2.sl +h libfile2.1 -L. -lfile1 +compat
        ln -s libfile1.sl libfile1.1
        ld main.o +compat -L. -lfile2 -lc
        # move dependent lib so dld can't find it. Even when we specify SHLIB_PATH dld won't be
        # able to find the dependent because we didn't link with +s
        mv libfile2.sl /var/tmp
        ln -s /var/tmp/libfile2.sl /var/tmp/libfile2.1
        a.out
        dld.sl: Unable to find library '1:./libfile2.1'
        export SHLIB_PATH=/var/tmp
        a.out
        dld.sl: Unable to find library '1:./libfile2.1'

chatr +s enable a.out

Library Example: Using 64-bit Mode Compatibility and Standard Shared Libraries

# build standard mode dlls
# libfile1.sl is a dependent of libfile2
 
ld -b file1.o -o libfile1.sl +h libfile1.1
mkdir TMP
ld -b +b $pwd/TMP file2.o -o libfile2.sl +h libfile2.1 -L. -lfile1
 
# build compatibility mode dlls
# libfile3.sl is a dependent of libfile4
ld -b file3.o -o libfile3.sl +h libfile3.1
ld -b file4.o -o libfile4.sl +b $pwd/TMP +h libfile4.1 +compat -L. -lfile3
ln -s libfile1.sl libfile1.1
ln -s libfile3.sl libfile3.1
mv libfile1.sl TMP
mv libfile3.sl TMP
cd TMP
ln -s libfile1.sl libfile1.1
ln -s libfile3.sl libfile3.1
cd ..# link with +b so ld will use RPATH at link time to find
# libfile1.sl (standard mode dll)
# the linker will not use RPATH to find libfile3.sl 
# (compatibility mode dll)
# Note that this is true in both a standard mode link and a
# compatibility mode link. The
# linker never uses RPATH to find any compatibility mode dlls
 
ld -b +b pwd/TMP main.o -o libfile5.sl +h libfile5.1 -L. -lfile2 -lfile4
ld: Can't find dependent library "./libfile3.sl"
ld -b +b pwd/TMP main.o -o libfile5a.sl +h libfile5.1 -L. -lfile2 -lfile4 +compat
ld: Can't find dependent library "./libfile3.sl"

Comparing Breadth-first and Depth-first Search in 64-bit Mode

lib1.sl has dependents lib2.sl, lib3.sl, and lib4.sl
lib2.sl has dependents lib2a.sl and lib2b.sl
lib3.sl has dependents lib3a.sl and lib3b.sl
lib3a.sl has dependent lib3aa.sl

                +-->lib2a.sl
                |
      +-->lib2.sl-->lib2b.sl
      |
lib1.sl-->lib3.sl-->lib3a.sl-->lib3aa.sl
      |         |
      |         +-->lib3b.sl
      +-->lib4.sl

lib1.sl->lib2.sl->lib3.sl->lib4.sl->lib2a.sl->lib2b.sl->lib3a.sl->lib3b.sl->lib3aa.sl

lib1.sl->lib2.sl->lib2a.sl->lib2b.sl->lib3.sl->lib3a.sl->lib3aa.sl->lib3b.sl->lib4.sl

Library Example: Using RPATH with Standard Mode Shared Library

ld -b bar.o -o libbar.sl
ld -b foo.o -o libfoo.sl -L. -lbar +b /var/tmp
# ld should look in /var/tmp to find libbar.sl since libfoo.sl 
# has an embedded RPATH of
# /var/tmp
mv libbar.sl /var/tmp
ld main.o -L. -lfoo -lc
# For compatibility mode dlls, embedded RPATHs are ignored
ld -b bar.o -o libbar.sl
ld -b foo.o -o libfoo.sl +compat -L. -lbar +b /var/tmp
# ld won't find libbar.sl since it does not look at embedded RPATHs
mv libbar.sl /var/tmp
ld main.o -L. -lfoo +compat -lc
ld: Can't find dependent library "libbar.sl"
Fatal error.

Library Example: Using 64-bit Standard Mode with Dynamic Path Searching and Two Libraries with the Same Basename

This example builds two shared libraries (libx.sl and liba.sl) with a dependency on the same third library (libb.sl). If the three shared libraries are moved to a new location, the dynamic loader successfully loads lib/libb.sl as a dependency of lib/libx.sl (rpath includes the lib directory).While loading lib/liba.sl, the dynamic loader unsuccessfully looks for ./libb.sl (rpath does not include the lib directory), then looks for previously-loaded libraries with a basename of libb.sl and successfully resolves libb.sl to lib/libb.sl that was loaded as a result of the load of lib/libx.sl.

$ cat liba.c
  extern int funcb();
  extern int funca() {
   funcb();
   return 0;
  }

$ cat libb.c
  extern int funcb() {
  return 0;
  }

$ cat libx.c
  extern int funca();
  extern int funcb();
  int funcx() {
    funca();
    funcb();
    return 0;
  }

$ cat main.c
  extern int funcx();
  int main() {
    funcx();
  }

Dependency structure:

  main
   |
   +-> libx
        |
        +-> liba
        |    |
        |    V
        +-> libb

$ cc -Ae +DA2.0W -c +z libb.c
$ ld -b -o libb.sl libb.o
$ cc -Ae +DA2.0W -c +z liba.c
$ ld -b -o liba.sl liba.o -L. -lb
$ cc -Ae +DA2.0W -c +z libx.c
$ ld -b -o libx.sl libx.o -L. -Llib -la -lb
$ cc -Ae +DA2.0W -o x main.c -L. -Llib -lx 
$ export SHLIB_PATH=/tmp
$ export LD_LIBRARY_PATH=/var/tmp
$ ./x
$ ldd -s ./x

  find library=libx.sl; required by ./x
    search path=/var/tmp  (LD_LIBRARY_PATH)
    trying path=/var/tmp/libx.sl
    search path=/tmp  (SHLIB_PATH)
    trying path=/tmp/libx.sl
    search path=.:lib:/usr/lib/pa20_64:/opt/langtools/lib/pa20_64:  (RPATH)
    trying path=./libx.sl
        libx.sl =>      ./libx.sl

 find library=libc.2; required by ./x
    search path=/var/tmp  (LD_LIBRARY_PATH)
    trying path=/var/tmp/libc.2
    search path=/tmp  (SHLIB_PATH)
    trying path=/tmp/libc.2
    search path=.:lib:/usr/lib/pa20_64:/opt/langtools/lib/pa20_64:  (RPATH)
    trying path=./libc.2
    trying path=lib/libc.2
    trying path=/usr/lib/p
        libc.2 =>       /usr/lib/pa20_64/libc.2

 find library=liba.sl; required by ./libx.sl
    search path=/var/tmp  (LD_LIBRARY_PATH)
    trying path=/var/tmp/liba.sl
    search path=/tmp  (SHLIB_PATH)
    trying path=/tmp/liba.sl
    search path=.:lib  (RPATH)
    trying path=./liba.sl
        liba.sl =>      ./liba.sl

 find library=libb.sl; required by ./libx.sl
    search path=/var/tmp  (LD_LIBRARY_PATH)
    trying path=/var/tmp/libb.sl
    search path=/tmp  (SHLIB_PATH)
    trying path=/tmp/libb.sl
    search path=.:lib  (RPATH)
    trying path=./libb.sl
        libb.sl =>      ./libb.sl

 find library=libdl.1; required by /usr/lib/pa20_64/libc.2
    search path=/var/tmp  (LD_LIBRARY_PATH)
    trying path=/var/tmp/libdl.1
    search path=/tmp  (SHLIB_PATH)
    trying path=/tmp/libdl.1
    search path=/usr/lib/pa20_64  (RPATH)
    trying path=/usr/lib/pa20_64/libdl.1
        libdl.1 =>      /usr/lib/pa20_64/libdl.1

 find library=libb.sl; required by ./liba.sl
    search path=/var/tmp  (LD_LIBRARY_PATH)
    trying path=/var/tmp/libb.sl
    search path=/tmp  (SHLIB_PATH)
    trying path=/tmp/libb.sl
    search path=.  (RPATH)
    trying path=./libb.sl
        libb.sl =>      ./libb.sl
    search path=./libb.sl  (BASENAME MATCH)

$ mv liba.sl libb.sl libx.sl lib/
$ ./x
$ ldd -s ./x

  find library=libx.sl; required by ./x
    search path=/var/tmp  (LD_LIBRARY_PATH)
    trying path=/var/tmp/libx.sl
    search path=/tmp  (SHLIB_PATH)
    trying path=/tmp/libx.sl
    search path=.:lib:/usr/lib/pa20_64:/opt/langtools/lib/pa20_64:  (RPATH)
    trying path=./libx.sl
    trying path=lib/libx.sl
        libx.sl =>      lib/libx.sl

  find library=libc.2; required by ./x
    search path=/var/tmp  (LD_LIBRARY_PATH)
    trying path=/var/tmp/libc.2
    search path=/tmp  (SHLIB_PATH)
    trying path=/tmp/libc.2
    search path=.:lib:/usr/lib/pa20_64:/opt/langtools/lib/pa20_64:  (RPATH)
    trying path=./libc.2
    trying path=lib/libc.2
    trying path=/usr/lib/pa20_64/libc.2
        libc.2 =>       /usr/lib/pa20_64/libc.2

  find library=liba.sl; required by lib/libx.sl
    search path=/var/tmp  (LD_LIBRARY_PATH)
    trying path=/var/tmp/liba.sl
    search path=/tmp  (SHLIB_PATH)
    trying path=/tmp/liba.sl
    search path=.:lib  (RPATH)
    trying path=./liba.sl
    trying path=lib/liba.sl
        liba.sl =>      lib/liba.sl

  find library=libb.sl; required by lib/libx.sl
    search path=/var/tmp  (LD_LIBRARY_PATH)
    trying path=/var/tmp/libb.sl
    search path=/tmp  (SHLIB_PATH)
    trying path=/tmp/libb.sl
    search path=.:lib  (RPATH)
    trying path=./libb.sl
    trying path=lib/libb.sl
        libb.sl =>      lib/libb.sl

  find library=libdl.1; required by /usr/lib/pa20_64/libc.2
    search path=/var/tmp  (LD_LIBRARY_PATH)
    trying path=/var/tmp/libdl.1
    search path=/tmp  (SHLIB_PATH)
    trying path=/tmp/libdl.1
    search path=/usr/lib/pa20_64  (RPATH)
    trying path=/usr/lib/pa20_64/libdl.1
        libdl.1 =>      /usr/lib/pa20_64/libdl.1

  find library=libb.sl; required by lib/liba.sl
    search path=/var/tmp  (LD_LIBRARY_PATH)
    trying path=/var/tmp/libb.sl
    search path=/tmp  (SHLIB_PATH)
    trying path=/tmp/libb.sl
    search path=.  (RPATH)
    trying path=./libb.sl
    search path=/lib/pa20_64:/usr/lib/pa20_64  (default)
    trying path=/lib/pa20_64/libb.sl
    trying path=/usr/lib/pa20_64/libb.sl
    search path=lib/libb.sl  (BASENAME MATCH)

Linking Libraries with +b pathlist

Library Example: Linking to Libraries with +b path_list in 64-bit Mode

cc -c +DD64 me.c 
ld -b me.o -o libme.sl 
ld -b bar.o -o libbar.sl -L. -lme +b /var/tmp mv libme.sl /var/tmp 
ld main.o -L. -lbar -lc

When linking main.o, the link order in the above example is:

./libbar.slfound

./libme.sl not found

/var/tmp/libme.sl found

./libc.sl not found

/usr/lib/pa20_64/libc.sl found

ld main.o -L. -lbar -lc mv libme.sl /var/tmp

instead of:

mv libme.sl /var/tmp ld main.o -L. -lbar -lc

the linker findslibme.sl in ./ at link time, and the dynamic loader finds libme.sl in /var/tmp at run time.

At run time, the dynamic loader searches paths to resolve external references made by main in the following order:

LD_LIBRARY_PATH to find libbar.sl not found

SHLIB_PATH to find libbar.sl not found

./libbar.sl (./libbar.sl) found

LD_LIBRARY_PATH to find libme.sl not found

SHLIB_PATH to find libme.sl not found

/var/tmp/libme.slfound

LD_LIBRARY_PATH to find libc.sl not found

SHLIB_PATH to find libc.sl not found

./libc.slnot found

/usr/lib/pa20_64/libc.slfound

Library Example: Linking to Libraries with +b path_list in 32-bit Mode

cc -c +DD32 me.c 
ld -b me.o -o libme.sl ld -b bar.o -o libbar.sl -L. -lme +b /var/tmp 
ld main.o -L. -lbar -lc mv libme.sl /var/tmp

./libbar.slfound

./libme.sl found

./libc.sl not found

/usr/lib/libc.slfound

mv libme.sl /var/tmp 
ld main.o -L. -lbar -lc

ld main.o -L. -lbar -lc mv libme.sl /var/tmp

the linker issues the following error:

ld: Can't find dependent library ./libme.sl
Fatal Error

Because libme.sl is specified with the -l option, it is subject to dynamic path searching.

At run time, the dynamic loader looks for shared libraries used by main in the following order:

./libbar.slfound

/var/tmp/libme.slfound

./libc.sl not found

/usr/lib/libc.slfound

Shared Library Management Routines

Shared Library Management Routine Summaries

The shl_load Routine Summary

All of the shl_load family routines use the same user interface in 32-bit and 64-bit mode linking.

Use the following shl_load routines for shared library management:
 

Routine	Action
shl_load and cxxshl_load	Explicitly load a shared library and a C++ (cftont) shared library, respectively. They have the same syntax. shl_load() lets you load a compatibility or standard mode shared library. It does depth-first searching.
shl_findsym	Finds the address of a global symbol in a shared library.
shl_get and shl_get_r	Get information about currently loaded libraries. shl_get_r is a thread-safe version of shl_get with the same syntax.
shl_gethandle and shl_gethandle_r	Get descriptor information about a loaded shared library. shl_gethandle_r is a thread-safe version of shl_gethandle with the same syntax.
shl_definesym	Adds a new symbol to the global shared library symbol table.
shl_getsymbols	Returns a list of symbols in a shared library.
shl_unload and cxxshl_unload	Unload a shared library and a C++ (cfront) shared library, respectively. They have the same syntax.

Except for shl_get and shl_gethandle, all these routines are thread safe.

These routines are described in the shl_load(3x) man page.

The dlopen Routines Summary

dlopen

dlclose

dlsym

dlerror

Use the following dl* routines for shared library management:
 

Routine	Action
dlopen	Loads a shared library. This routine does breadth-first searching.
dlerror	Prints the last error message recorded by dld.
dlsym	Gets the address of a symbol in a shared library.
dlget	Returns information on a loaded module.
dlmodinfo	Returns information about a loaded module.
dlgetname	Retrieves the name of a loaded module given a load model descriptor.
dlclose	Unloads a shared library previously loaded by dlopen().

All the dlopen routines are thread-safe.

These routines are described in the dl*(3C) man pages.

Related Files and Commands

Shared Library Header Files

#include <dl.h>

Similarly, if you are using the dlopen family of routines, include /usr/include/dlfcn.h.

#include <dlfcn.h>

#include <errno.h>

Using Shared Libraries with cc and ld Options

Some 32-bit mode implementations do not, by default, export all symbols defined by a program (instead exporting only those symbols imported by a shared library seen at link time). Use the -E option to ld to ensure that all symbols defined in the program are available to the loaded libraries. This is the default behavior in 64-bit mode.

To create shared libraries, compile source files with +z or +Z and link the resultant object files with the -b with the cc or ld command.

Initializers for Shared Libraries

When a program begins execution, its initializers are called before any other user code is executed.This allows for setup at initialization and cleanup at termination. Also, when a shared library is explicitly loaded using shl_load or dlopen or unloaded using shl_unload or dlclose, its initializers and terminators are called at the appropriate time.

In 64-bit mode, you can specify initializers and terminators even for archive libraries or nonshared executables.

Styles of Initializers

Init/fini style. (Not supported in HP-UX 10.X)

HP-UX 10.X style.

Init/Fini Style Initializers

Init

The C compiler pragma "init" can be used to declare these functions. For example:

#pragma init "my_init"void my_init() { ... do some initializations ... }

Use the +init option to specify the initializer functions, to be invoked in reverse order, the order the functions appear right to left on the command line. Initializers are called in depth-first order. For example, when a shared library is loaded, the initializers in all its dependent libraries are called first.

Do not use +init with the -r option. (The linker ignores the +init option.)

You can specify more than one initializer function on the command line with multiple option-symbol pairs, that is, each function you specify must be preceded by the +init option.

Fini

The C compiler pragma "fini" can be used to create them. For example:

#pragma fini "my_fini"void my_fini() { ... do some clean up ... }

Use the +fini option to specify the terminator (finalizer) functions, to be invoked in forward order, the order the functions appear left to right on the command line. The terminator functions are called in reverse of the depth-first order of initializers.

Do not use +fini with the -r option. (The linker ignores the +fini option.)

You can specify more than one terminator function on the command line with multiple option-symbol pairs, that is, each function you specify must be preceded by the +fini option.

HP-UX-10.X Style Initializers

$ ld -b foo.o +I my_10x_init -o libfoo.sl
#include <dl.h>
 
void my_10x_init(shl_t handle, int loading)
{       /* handle is the shl_load API handle for the shared library being initialized. */
        /* loading is non-zero at startup and zero at termination. */
 
 
        if (loading) {
                ... do some initializations ...
 
else {          ... do some clean up ...
        }}

See Using HP-UX 10.X Style Initializers for more information on using these initializers.

Using Init/Fini Initializers

Init and Fini Usage Example

Ordering Within an Executable or Shared Library

Ordering Among Executables and Shared Libraries

Init and Fini Usage Example

C source for lib1.sl (file lib1.c):

lib1()
{
    printf("lib1\n");
}

void
lib1_init()
{
    printf("lib1_init\n");
}

void
lib1_fini()
{
    printf("lib1_fini\n");
}

ib2()
{
    printf("lib2\n");
}

void
lib2_init()
{
    printf("lib2_init\n");
}

void
lib2_fini()
{
    printf("lib2_fini\n");
}

ib3()
{
    printf("lib3\n");
}

#pragma init "lib3_init"

void

lib3_init()
{
    printf("lib3_init\n");
}

#pragma fini "lib3_fini"

void
lib3_fini()
{
    printf("lib3_fini\n");}

$ cc +DD64 lib1.c lib2.c lib3.c main.c -c;
$ ld -b lib3.o -o lib3.sl;
$ ld -b +init lib2_init +fini lib2_fini lib2.o -o lib2.sl;
$ ld -b +init lib1_init +fini lib1_fini lib1.o ./lib3.sl -o \
lib1.sl;
$ cc -L. +DD64 main.o -l1 -l2 -lc;

lib2_init
lib3_init
lib1_init
lib1
lib2
lib3
lib1_fini
lib3_fini
lib2_fini

Ordering Within an Executable or Shared Library

Inits in .o (object) files or .a (archive) files are called in the reverse order of the link line.

Finis in .o or .a files are called in forward order of the link line.

HP-UX 10.X style initializers are called in forward order of the +I options specified on the link line when loading a shared library. They are then called in reverse order when unloading the library.

HP-UX 10.X style initializers are called after inits and before finis.

Any inits or finis in archive (.a) files are called only if the .o which contains it is used during the link. Use the linker -v option to determine which .o files within an archive file were used.

Shared libraries on the link line (dependent libraries) follow the ordering described in Ordering Among Executables and Shared Libraries.

$ ld -b first_64bit.o -l:libfoo.sl second_64bit.o my_64bit.a +I first_10x_init +I second_10x_init -o libbar.sl

inits from any .o files used in my_64bit.a

inits in second_64bit.o

inits in first_64bit.o

first_10x_init

second_10x_init

second_10x_init

first_10x_init

finis in first_64bit.o

finis in second_64bit.o

finis from any .o files used in my_64bit.a

Ordering Among Executables and Shared Libraries

When loading, the inits and HP-UX 10.X style initializers of any dependent libraries are called before the ones in the current library.

When unloading, the finis and HP-UX 10.X style initializers of any dependent libraries are called after the finis of the current library.

If a shared library is itself a dependent of one of its dependents (a "circular" dependency), no ordering between them is guaranteed.

$  ld -b foo.o -lB -lC -o libA.sl

inits in C

inits in B

inits in A

finis inA

finis in B

finis in C

Using HP-UX 10.X Style Initializers

When calling initializers for implicitly loaded libraries, the dynamic loader waits until all libraries have been loaded before calling the initializers. It calls the initializers in depth-first order-that is, the initializers are called in the reverse order in which the libraries are searched for symbols. All initializers are called before the main program begins execution.

When calling the initializer for explicitly loaded libraries, the dynamic loader waits until any dependent libraries are loaded before calling the initializers. As with implicitly loaded libraries, initializers are called in depth-first order.

Note that initializers can be disabled for explicitly loaded libraries with the BIND_NOSTART flag to shl_load. For more information, see The shl_load and cxxshl_load Routines .

This section contains the following topics:

Declaring the Initializer with the +I Option

Initializer Syntax

Example: An Initializer for Each Library

Example: A Common Initializer for Multiple Libraries

Declaring the Initializer with the +I Option

 +I initializer

Multiple initializers may be called by repeating the +Iinitializer option.

For example, to create a shared library named libfoo.sl that uses an initializer named init_foo, use this linker command line:

$ ld -b -o libfoo.sl libfoo.o +I init_foo

Order of Execution of Multiple Initializers

Initializers behave the same as other symbols; once they are bound they cannot be overridden with a new symbol through the use of shl_definesym() or by loading a more visible occurrence of the initializer symbol with the BIND_FIRST flag. What this means is that once the initializer is executed upon a load, it is guaranteed to be the same initializer that is called on an explicit unload.

Initializer Syntax

void initializer( shl_t handle,
                  int loading )

initializer

The name of the initializer as specified with the +I linker option.

handle

The initializer is called with this parameter set to the handle of the shared library for which it was invoked.

loading

The initializer is called with this parameter set to -1 (true) when the shared library is loaded and 0 (false) when the library is unloaded.

It is strongly recommended that initializers be defined with names which do not cause name collisions with other user-defined names in order to avoid overriding behavior of shared library symbol binding.

Accessing Initializers' Addresses

If only one initializer is specified for a given library, its address is still available through the initializer field of a shared library descriptor. If more than one initializer is specified, the initializer field will be set to NO_INITIALIZER. Access to multiple initializers can then be accomplished through the use of shl_getsymbols(). (The shl_getsymbols() routine can also access a single initializer.)

To access initializers, use the new flag, INITIALIZERS, in the shl_getsymbols() routine. This flag can be ORed with the NO_VALUES and GLOBAL_VALUES flags. For example,

shl_getsymbols(handle,
               TYPE_PROCEDURE,
               INITIALIZERS | GLOBAL_VALUES,
               malloc,
               &symbol_array);

For more information on the usage of shl_getsymbols(), see The shl_getsymbols Routine.

Example: An Initializer for Each Library

#include <stdio.h>
#include <dl.h>
/*
 * This is the local initializer that is called when the libfoo.sl
 * is loaded and unloaded:
 */
void init_foo(shl_t hndl, int loading)
{
  if (loading)
    printf("libfoo loaded\n");
  else

    printf("libfoo unloaded\n");
}
 
float in_to_cm(float in)              /* convert inches to centimeters */
{
  return (in * 2.54);
}
 
float gal_to_l(float gal)             /* convert gallons to litres */
{
  return (gal * 3.79);
}
 
float oz_to_g(float oz)               /* convert ounces to grams */
{
  return (oz * 28.35);
}

$ cc -Aa -c +z libfoo.c
$ ld -b -o libfoo.sl +I init_foo libfoo.o

#include <stdio.h>
#include <dl.h>
main()
{
float (*in_to_cm)(float), (*gal_to_l)(float), (*oz_to_g)(float);
shl_t hndl_foo;
/*
 * Load libfoo.sl and find the required symbols:
 */
if ((hndl_foo = shl_load("libfoo.sl",
     BIND_IMMEDIATE, 0)) == NULL)
   perror("shl_load: error loading libfoo.sl"), exit(1);
   
if (shl_findsym(&hndl_foo, "in_to_cm", TYPE_PROCEDURE,
   (void *) &in_to_cm))
   perror("shl_findsym: error finding in_to_cm"), exit(1);
   
if (shl_findsym(&hndl_foo, "gal_to_l", TYPE_PROCEDURE,
   (void *) &gal_to_l))
   perror("shl_findsym: error finding gal_to_l"), exit(1);
   
if (shl_findsym(&hndl_foo, "oz_to_g", TYPE_PROCEDURE,
   (void *) &oz_to_g))
   perror("shl_findsym: errror finding oz_to_g"), exit(1);
 /*
  * Call routines from libfoo.sl:
  */
 printf("1.0in  = %5.2fcm\n", (*in_to_cm)(1.0));
 printf("1.0gal = %5.2fl\n", (*gal_to_l)(1.0));
 printf("1.0oz  = %5.2fg\n", (*oz_to_g)(1.0));
 /*
  * Unload the library:
  */
 shl_unload(hndl_foo);
}

$ cc -Aa testlib.c -o testlib -ldld
$ testlib
 
libfoo loaded
1.0in  =  2.54cm
1.0gal =  3.79l
1.0oz  = 28.35g
libfoo unloaded

Example: A Common Initializer for Multiple Libraries

This is easily done by defining load and unload functions in each library. When _INITIALIZER is called, it uses shl_findsym to find and call the load or unload function (depending on the value of the loading flag).

The following example shows the source for an _INITIALIZER function:
C Source for _INITIALIZER (file init.c)

#include <dl.h>
/*
 * Global initializer used by shared libraries that have
 * registered it:
 */
void _INITIALIZER(shl_t hand, int loading)
{
 void (*load_unload)();
 
 if (loading)
  shl_findsym(&hand, "load", TYPE_PROCEDURE, (void *) &load_unload);
 else
    shl_findsym(&hand, "unload", TYPE_PROCEDURE, (void *) &load_unload);
 
 (*load_unload) ();           /* call the function */
}

#include <stdio.h>
#include <dl.h>
void load()                   /* called after libunits.sl loaded */

 {
  printf("libunits.sl loaded\n");
 }
 
void unload()                 /* called after libunits.sl unloaded */
 {
  printf("libunits.sl unloaded\n");
 }
 
extern void _INITIALIZER();
 
float in_to_cm(float in)      /* convert inches to centimeters */
 {
  return (in * 2.54);
 }
 
float gal_to_l(float gal)     /* convert gallons to litres */
 {
  return (gal * 3.79);
 }
 
float oz_to_g(float oz)       /* convert ounces to grams */
 {
  return (oz * 28.35);
 }

#include <stdio.h>
void load()                     /* called after libtwo.sl loaded */
{
  printf("libtwo.sl loaded\n");
}
void unload()                   /* called after libtwo.sl unloaded */
{
  printf("libtwo.sl unloaded\n");
}
 
extern void _INITIALIZER();
void (*init_ptr)() = _INITIALIZER;
 
void foo()
{
  printf("foo called\n");
}
void bar()
{
  printf("bar called\n");
}

$ cc -Aa -c +z libunits.c
$ ld -b -o libunits.sl +I _INITIALIZER libunits.o
$ cc -Aa -c +z libtwo.c
$ ld -b -o libtwo.sl +I _INITIALIZER libtwo.o

#include <stdio.h>
#include <dl.h>
main()
{
 float (*in_to_cm)(float), (*gal_to_l)(float), (*oz_to_g)(float);
 void (*foo)(), (*bar)();
 shl_t hndl_units, hndl_two;
 
 /*
  * Load libunits.sl and find the required symbols:
  */
 if ((hndl_units = shl_load("libunits.sl", BIND_IMMEDIATE, 0)) == NULL)
   perror("shl_load: error loading libunits.sl"), exit(1);
 if (shl_findsym(&hndl_units, "in_to_cm",
     TYPE_PROCEDURE, (void *) &in_to_cm))
     perror("shl_findsym: error finding in_to_cm"), exit(1);
   
 if (shl_findsym(&hndl_units, "gal_to_l",
     TYPE_PROCEDURE, (void *) &gal_to_l))
     perror("shl_findsym: error finding gal_to_l"), exit(1);
     
 if (shl_findsym(&hndl_units, "oz_to_g",
     TYPE_PROCEDURE, (void *) &oz_to_g))
     perror("shl_findsym: errror finding oz_to_g"), exit(1);
     
 /*
  * Load libtwo.sl and find the required symbols:
  */
 if ((hndl_two = shl_load("libtwo.sl", BIND_IMMEDIATE, 0)) == NULL)
   perror("shl_load: error loading libtwo.sl"), exit(1);
 if (shl_findsym(&hndl_two, "foo", TYPE_PROCEDURE, (void *) &foo))
   perror("shl_findsym: error finding foo"), exit(1);
 if (shl_findsym(&hndl_two, "bar", TYPE_PROCEDURE, (void *) &bar))
   perror("shl_findsym: error finding bar"), exit(1);
 /*
  * Call routines from libunits.sl:
  */
 printf("1.0in  = %5.2fcm\n", (*in_to_cm)(1.0));
 printf("1.0gal = %5.2fl\n", (*gal_to_l)(1.0));
 printf("1.0oz  = %5.2fg\n", (*oz_to_g)(1.0));
 /*
  * Call routines from libtwo.sl:
  */
 (*foo)();
 (*bar)();
 /*
  * Unload the libraries so we can see messages displayed by initializer:
  */
 shl_unload(hndl_units);
 shl_unload(hndl_two);
}

$ cc -Aa -Wl,-E -o testlib2 testlib2.c init.c -ldld

Finally, the output from running testlib2 is shown:

Output of testlib2

$ cc -Aa testlib2.c -o testlib2 -ldld
$ testlib2
 
libunits.sl loaded
libtwo.sl loaded
1.0in  =  2.54cm
1.0gal =  3.79l
1.0oz  = 28.35g
foo called
bar called
libunits.sl unloaded
libtwo.sl unloaded

The shl_load Shared Library Management Routines

The shl_load and cxxshl_load Routines

Syntax

shl_t shl_load( const char * path,
                int flags,
                long address )

Parameters

path

A null-terminated character string containing the path name of the shared library to load.

flags

Specifies when the symbols in the library should be bound to addresses. It must be one of these values, defined in <dl.h>:

BIND_IMMEDIATE

Bind the addresses of all symbols immediately upon loading the library.

BIND_DEFERRED

Bind the addresses when they are first referenced.

Be aware that BIND_IMMEDIATE causes the binding of all symbols, and the resolution of all imports, even from older versioned modules in the shared library. If symbols are not accessible because they come from old modules, they are unresolved and shl_load may fail.

In addition to the above values, the flags parameter can be ORed with the following values:

BIND_NONFATAL

Allow binding of unresolved symbols.

BIND_VERBOSE

Make dynamic loader display verbose messages when binding symbols.

BIND_FIRST

Insert the loaded library before all others in the current link order.

DYNAMIC_PATH

Causes the dynamic loader to perform dynamic library searching when loading the library. The +s and +b options to the ld command determine the directories the linker searches. This is the default mode for the 64-bit mode linker if +compat linker option is not specified.

BIND_NOSTART

Causes the dynamic loader to not call the initializer, even if one is declared for the library, when the library is loaded or on a future call to shl_load or dlopen. This also inhibits a call to the initializer when the library is unloaded.

BIND_RESTRICTED

Causes the search for a symbol definition to be restricted to those symbols that were visible when the library was loaded.

BIND_TOGETHER

Causes the library being loaded and all its dependent libraries to be bound together rather than each independently. Use this when you have interdependent libraries and you are using BIND_FIRST.

BIND_BREADTH_FIRST

64-bit mode only:
Causes the dependent libraries to be loaded breadth first. By default, the 64-bit mode shl_load loads dependent libraries depth-first.

These flags are discussed in detail in shl_load Example .

address

Specifies the virtual address at which to attach the library. Set this parameter to 0 (zero) to tell the system to choose the best location. This argument is currently ignored; mapping a library at a user-defined address is not currently supported.

Return Value

ENOEXEC

The specified path is not a shared library, or a format error was detected in this or another library.

ENOSYM

A symbol needed by this library or another library which this library depends on could not be found.

ENOMEM

There is insufficient room in the address space to load the shared library.

EINVAL

The requested shared library address was invalid.

ENOENT

The specified path does not exist.

EACCESS

Read or execute permission is denied for the specified path.

Description

However, programs are not restricted to using shared libraries only in that situation. For example, rather than linking with any required libraries, a program could explicitly load libraries as they are needed. One possible reason for doing this is to minimize virtual memory overhead. To keep virtual memory resource usage to a minimum, a program could load libraries with shl_load and unload with shl_unload when the library is no longer needed. However, it is normally not necessary to incur the programming overhead of loading and unloading libraries yourself for the sole reason of managing system resources.

Note that if shared library initializers have been declared for an explicitly loaded library, they are called after the library is loaded. For details, see Initializers for Shared Libraries.

To explicitly load a shared library, use the shl_load routine. If loading a C++ (cfront) library, use the cxxshl_load routine. This ensures that constructors of nonlocal static objects are executed when the library is loaded. The syntax of cxxshl_load is the same as that of shl_load.

In 64-bit mode, shl_load lets you load a compatibility or standard mode shared libraries. The BIND_BREADTH_FIRST flag overrides the default depth-first loading mechanism.

shl_load Usage

Hard-code the library name into the program (the easiest method).

Get the library name from an environment variable using the getenv library routine (see getenv(3C)).

Get the library path name from the command line through argv.

Read the library name from a configuration file.

Prompt for the library path name at run time.

Once a library is explicitly loaded, use the shl_findsym routine to get pointers to functions or data contained in the library; then call or reference them through the pointers. This is described in detail inThe shl_findsym Routine .

Use caution when building shared libraries with external library dependencies. Any library that contains Thread Local Storage (TLS) should not be used as a dependency. If a dependent library contains TLS, and it is loaded during program startup (that is, not linked against the executable), the dynamic loader fails to perform the operation.

shl_load Example

The function then attempts to load the specified library. If successful, it returns the shared library handle, of type shl_t. If an error occurs, it displays an error message and exits. This function is used later in The shl_findsym Routine .
load_lib - Function to Load a Shared Library

#include        <stdio.h>      /* contains standard I/O defs           */
#include        <stdlib.h>     /* contains getenv definition           */
#include        <dl.h>         /* contains shared library type defs    */
 
shl_t load_lib(int argc,
               char * argv[])   /* pass argc and argv from main */
{
  shl_t   lib_handle;             /* temporarily holds library handle  */
  char    lib_path[MAXPATHLEN];   /* holds library path name           */
  char    *env_ptr;               /* points to SHLPATH variable value  */
  /*
   * Get the shared library path name:
   */
  if (argc > 1)               /* library path given on command line */
    strcpy(lib_path, argv[1]);
  else                        /* get lib_path from SHLPATH variable */
    {
      env_ptr = getenv("SHLPATH");
      if (env_ptr != NULL)
        strcpy(lib_path, env_ptr);
      else                    /* prompt user for shared library path */
        {
          printf("Shared library to use >> ");
          scanf("%s", lib_path);
        }
    }
  /*
   * Dynamically load the shared library using BIND_IMMEDIATE binding:
   */
  lib_handle = shl_load( lib_path, BIND_IMMEDIATE, 0);
  if (lib_handle == NULL)
    perror("shl_load: error loading library"), exit(1);
  return lib_handle;
}

BIND_NONFATAL Modifier

shl_t libH;
   . . .
libH = shl_load("libxyz.sl", BIND_IMMEDIATE | BIND_NONFATAL, 0);

BIND_VERBOSE Modifier

shl_t libH;
   . . .
libH = shl_load("libxyz.sl", BIND_IMMEDIATE | BIND_VERBOSE, 0);

BIND_FIRST Modifier

shl_t libH;
  . . . 
libH = shl_load("libpdq.sl", BIND_DEFERRED | BIND_FIRST, 0);

DYNAMIC_PATH Modifier

BIND_NOSTART Modifier

BIND_RESTRICTED Modifier

When used with only the BIND_DEFERRED flag, it has this behavior: When a symbol is referenced and needs to be bound, this flag causes the search for the symbol definition to be restricted to those symbols that were visible when the library was loaded. If a symbol definition cannot be found within this restricted set, it results in a run-time symbol-binding error.

When used with BIND_DEFERRED and the BIND_NONFATAL modifier, it has the same behavior, except that when a symbol definition cannot be found, the dynamic loader will then look in the global symbol set. If a definition still cannot be found within the global set, a run-time symbol-binding error occurs.

BIND_TOGETHER Modifier

BIND_FIRST | BIND_TOGETHER causes the library being loaded and its dependent libraries to be bound all at the same time, thereby resolving interdependencies. If you are not using BIND_FIRST, libraries are bound together by default so this option has no effect.

BIND_BREADTH_FIRST Modifier

This flag causes the dependent libraries to be loaded breadth first. By default, the 64-bit mode shl_load loads dependent libraries depth-first. This modifier overrides the default load order.

Binding Flags Examples

When using BIND_DEFERRED or BIND_IMMEDIATEwithoutBIND_FIRST, these libraries are loaded such that all symbols are visible and the interdependencies are resolved:

shl_t libE;
libE = shl_load("libE.sl", BIND_IMMEDIATE, 0);  
shl_load succeeds.

libE = shl_load("libE.sl", BIND_IMMEDIATE | BIND_FIRST, 0); 
shl_load fails.

libE = shl_load("libE.sl", BIND_IMMEDIATE | BIND_FIRST | BIND_TOGETHER, 0); 
shl_load succeeds.

The shl_findsym Routine

Syntax

int shl_findsym( shl_t * handle,
                 const char * sym,
                 short type,
                 void * value )

Parameters

handle

A pointer to a shared library handle of the library to search for the symbol name sym. This handle could be obtained from the shl_get routine (described in the The shl_get and shl_get_r Routines). handle can also point to:

NULL

If a pointer to NULL is specified, shl_findsym searches all loaded libraries for sym. If sym is found, shl_findsym sets handle to a pointer to the handle of the shared library containing sym. This is useful for determining which library a symbol resides in. For example, the following code sets handle to a pointer to the handle of the library containing symbol _foo:

shl_t handle;
handle = NULL;
shl_findsym(&handle,"_foo",...);

PROG_HANDLE

This constant, defined in dl.h, tells shl_findsym to search for the symbol in the program itself. This way, any symbols exported from the program can be accessed explicitly.

sym

A null-terminated character string containing the name of the symbol to search for.

type

The type of symbol to look for. It must be one of the following values, defined in <dl.h>:

TYPE_PROCEDURE

Look for a function or procedure.

TYPE_DATA

Look for a symbol in the data segment (for example, variables).

TYPE_UNDEFINED

Look for any symbol.

TYPE_STORAGE

32-bit mode only.

TYPE_TSTORAGE

32-bit mode only.

value

A pointer in which shl_findsym stores the address of sym, if found.

Return Value

ENOEXEC

A format error was detected in the specified library.

ENOSYM

A symbol on which sym depends could not be found.

EINVAL

The specified handle is invalid.

Description

To call a routine in an explicitly loaded library

declare a pointer to a function of the same type as the function in the shared library

using shl_findsym with the type parameter set to TYPE_PROCEDURE, find the symbol in the shared library and assign its address to the function pointer declared in Step 1

call the pointer to the function obtained in Step 2, with the correct number and type of arguments

declare a pointer to a data structure of the same type as the data structure to access in the library

using shl_findsym with the type parameter set to TYPE_DATA, find the symbol in the shared library and assign its address to the pointer declared in Step 1

access the data through the pointer obtained in Step 2

shl_findsym Example

gopen()

opens the graphics device for output

gclose()

closes the graphics device

move2d(x,y)

moves to pixel location x,y

draw2d(x,y)

draws to pixel location x,y from current x,y

maxX

contains the maximum X pixel location on the output device

maxY

contains the maximum Y pixel location on the output device

#include <stdio.h>      /* contains standard I/O defs        */
#include <stdlib.h>     /* contains getenv definition        */
#include <dl.h>         /* contains shared library type defs */
/*
 * Define linker symbols:
 */
 
#define GOPEN   "gopen"
#define GCLOSE  "gclose"
#define MOVE2D  "move2d"
#define DRAW2D  "draw2d"
#define MAXX    "maxX"
#define MAXY    "maxY"
 
shl_t   load_lib(int argc, char * argv[]);
main(int argc,
     char * argv[])
{
  shl_t lib_handle;           /* handle of shared library       */
  int   (*gopen)(void);       /* opens the graphics device      */
  int   (*gclose)(void);      /* closes the graphics device     */
  int   (*move2d)(int, int);  /* moves to specified x,y location */
  int   (*draw2d)(int, int);  /* draw line to specified x,y location*/
  int   *maxX;                /* maximum X pixel on device      */
  int   *maxY;                /* maximum Y pixel on device      */
 
  lib_handle = load_lib(argc, argv);  /* load required shared library */
  /*
   * Get addresses of all functions and data that will be used:
   */
  if (shl_findsym(&lib_handle, GOPEN, TYPE_PROCEDURE, (void *) &gopen))
    perror("shl_findsym: error finding function gopen"), exit(1);
  if (shl_findsym(&lib_handle, GCLOSE, TYPE_PROCEDURE, (void *) &gclose))
    perror("shl_findsym: error finding function gclose"), exit(1);
  if (shl_findsym(&lib_handle, MOVE2D, TYPE_PROCEDURE, (void *) &move2d))
    perror("shl_findsym: error finding function move2d"), exit(1);
  if (shl_findsym(&lib_handle, DRAW2D, TYPE_PROCEDURE, (void *) &draw2d))
    perror("shl_findsym: error finding function draw2d"), exit(1);
  if (shl_findsym(&lib_handle, MAXX, TYPE_DATA, (void *) &maxX))
    perror("shl_findsym: error finding data maxX"), exit(1);
  if (shl_findsym(&lib_handle, MAXY, TYPE_DATA, (void *) &maxY))
    perror("shl_findsym: error finding data maxY"), exit(1);
  /*
   * Using the routines, draw a line from (0,0) to (maxX,maxY):

   */
  (*gopen)();                 /* open the graphics device       */
  (*move2d)(0,0);             /* move to pixel 0,0              */
  (*draw2d)(*maxX,*maxY);     /* draw line to maxX,maxY pixel   */
  (*gclose)();                /* close the graphics device      */
}

$ cc -Aa -o drawline shl_findsym.c load_lib.c -ldld
$ SHLPATH=/usr/lib/libgrphdd.sl
$ export SHLPATH
$ drawline

The shl_get and shl_get_r Routines

Syntax

int shl_get( int index,
             struct shl_descriptor **desc )

Parameters

index

Specifies an ordinal number of the shared library in the process. For libraries loaded implicitly (at startup time), index is the ordinal number of the library as it appeared on the command line. For example, if libc was the first library specified on the ld command line, then libc has an index of 1. For explicitly loaded libraries, index corresponds to the order in which the libraries were loaded, starting after the ordinal number of the last implicitly loaded library. Two index values have special meaning:

0

Refers to the main program itself

-1

Refers to the dynamic loader (dld.sl).

A shared library's index can be modified during program execution by either of the following events:

The program loads a shared library with the BIND_FIRST modifier to shl_load. This increments all the shared library indexes by one.
The program unloads a shared library with shl_unload. Any libraries following the unloaded library have their index decremented by one.

desc

Returns a pointer to a statically allocated buffer (struct shl_descriptor **) containing a shared library descriptor. The structure contains these important fields:

tstart

The start address (unsigned long) of the shared library text segment.

tend

The end address (unsigned long) of the shared library text segment.

dstart

The start address (unsigned long) of the shared library data segment.

dend

The end address (unsigned long) of the shared library bss segment. The data and bss segments together form a contiguous memory block starting at dstart and ending at dend.

handle

The shared library's handle (type shl_t).

filename

A character array containing the library's path name as specified at link time or at explicit load time.

initializer

A pointer to the shared library's initializer routine (see Initializers for Shared Libraries. It is NULL if there is no initializer. This field is useful for calling the initializer if it was disabled by the BIND_NOSTART flag to shl_load.

If the shared library has multiple initializers, this field will also be set to NULL. Multiple initializers can be found with shl_getsymbols, described later in this chapter.

This buffer is statically allocated. Therefore, if a program intends to use any of the members of the structure, the program should make a copy of the structure before the next call to shl_get. Otherwise, shl_get will overwrite the static buffer when called again.

Return Value

Description

Other than obtaining interesting information, this routine is of little use to most programmers. A typical use might be to display the names and starting/ending address of all shared libraries in a process's virtual memory address space.

Example

#include        <stdio.h>      /* contains standard I/O defs           */
#include        <dl.h>         /* contains shared library type defs    */
void    show_loaded_libs(void)
{
int     idx;
struct  shl_descriptor  *desc;
 
  printf("SUMMARY of currently loaded libraries:\n");
  printf("%-25s  %10s  %10s  %10s  %10s\n",
      "___library___", "_tstart_", "__tend__", "_dstart_", "__dend__");
 
  idx = 0;
  for (idx = 0; shl_get(idx, &desc) != -1; idx++)
    printf("%-25s  %#10lx  %#10lx  %#10lx  %#10lx\n",
     desc->filename, desc->tstart, desc->tend, desc->dstart, desc->dend);
}

SUMMARY of currently loaded libraries:
___library___         _tstart_    __tend__    _dstart_    __dend__
./a.out                 0x1000      0x1918  0x40000000  0x40000200
/usr/lib/libdld.sl  0x800ac800  0x800ad000  0x6df62800  0x6df63000
/usr/lib/libc.sl    0x80003800  0x80091000  0x6df63000  0x6df85000

The shl_gethandle and shl_gethandle_r Routines

Syntax

int shl_gethandle( shl_t handle,
                   struct shl_descriptor **desc )

Parameters

handle

The handle of the shared library you want information about. This handle is the same as that returned by shl_load.

desc

Points to shared library descriptor information - the same information returned by the shl_get routine. The buffer used to store this desc information is static, meaning that subsequent calls to shl_gethandle will overwrite the same area with new data. Therefore, if you need to save the desc information, copy it elsewhere before calling shl_gethandle again.

Return Value

Description

Example

#include <stdio.h>
#include <dl.h>
 
int show_lib_info(shl_t libH)
{
struct shl_descriptor *desc;
 
  if (shl_gethandle(libH, &desc) == -1)
  {
    fprintf(stderr, "Invalid library handle.\\n");
    return -1;
  }
  printf("library path:    %s\\n", desc->filename);
  printf("text start:      %#10lx\\n", desc->tstart);
  printf("text end:        %#10lx\\n", desc->tend);
  printf("data start:      %#10lx\\n", desc->dstart);
  printf("data end:        %#10lx\\n", desc->dend);
  return 0;
}

The shl_definesym Routine

Syntax

int shl_definesym( const char *sym,
                   short type,
                   long value,
                   int flags )

Parameters

sym

A null-terminated string containing the name of the symbol to change or to add to the process's shared library symbol table.

type

The type of symbol - either TYPE_PROCEDURE or TYPE_DATA.

value

If value falls in the address range of a currently loaded library, an association will be made and the symbol is undefined when the library is unloaded. (Note that memory dynamically allocated with malloc(3C) does not fall in the range of any library.) The defined symbol may be overridden by a subsequent call to this routine or by loading a more visible library that provides a definition for the symbol.

flags

Must be set to zero.

Return Value

Description

There are two main reasons to add or change shared library symbol table entries:

to generate symbol definitions as the program runs - for example, aliasing one symbol with another

to override a current definition

The incomplete executable always uses its own definition for any data (storage) symbol, even if a more visible one is provided.

The incomplete executable only uses a more visible code symbol if the main program itself does not provide a definition.

The shl_getsymbols Routine

Syntax

int shl_getsymbols( shl_t handle,
                    short type,
                    int flags,
                    void * (*memfunc)(),
                    struct shl_symbol **symbols )

Parameters

handle

The handle of the shared library whose symbols you want to retrieve. If handle is NULL, shl_getsymbols returns symbols that were defined with the shl_definesym routine.

type

Defines the type of symbol to retrieve. It must be one of the following values, which are defined as constants in <dl.h>:

TYPE_PROCEDURE

Retrieve only function or procedure symbols.

TYPE_DATA

Retrieve only symbols from the data segment (for example, variables).

TYPE_UNDEFINED

Retrieve all symbols, regardless of type.

TYPE_STORAGE

32-bit mode only.

TYPE_TSTORAGE

32-bit mode only.

flags

Defines whether to retrieve import or export symbols from the library. An import symbol is an external reference made from a library. An export symbol is a symbol definition that is referenced outside the library. In addition, any symbol defined by shl_definesym is an export symbol. Set this argument to one of the following values (defined in <dl.h>):

IMPORT_SYMBOLS

To return import symbols.

EXPORT_SYMBOLS

To return export symbols.

INITIALIZERS

To return initializer symbols.

One of the following modifiers can be ORed with both the EXPORT_SYMBOLS and the INITIALIZERS flags:

NO_VALUES

Do not calculate the value field of the shl_symbol structure for symbols. The value field has an undefined value.

GLOBAL_VALUES

For symbols that are defined in multiple libraries, this flag causes shl_getsymbols to return the most-visible occurrence, and to set the value and handle fields of the shl_symbol structure (defined in the description of the symbols parameter).

memfunc

Points to a function that has the same interface (calling conventions and return value) as malloc(3C). The shl_getsymbols function uses this function to allocate memory to store the array of symbol records, symbols.

symbols

This points to an array of symbol records for all symbols that match the criteria determined by the type and value parameters. The type of these records is struct shl_symbol, defined in <dl.h> as:

struct shl_symbol {
  char * name;
  short  type;
  void * value;
  shl_t  handle;
};

The members of this structure are described in The shl_symbol Structure.

Return Value

ENOEXEC

A format error was detected in the specified library.

ENOSYM

Some symbol required by the shared library could not be found.

EINVAL

The specified handle is invalid.

ENOMEM

memfunc failed to allocate the requested memory.

The shl_symbol Structure

name

Contains the name of a symbol.

type

Contains the symbol's type: TYPE_PROCEDURE, TYPE_DATA, or TYPE_STORAGE. TYPE_STORAGE is a data symbol used for C uninitialized global variables or FORTRAN common blocks.

value

Contains the symbol's address. It is valid only if EXPORT_SYMBOLS is specified without the NO_VALUES modifier.

handle

Contains the handle of the shared library in which the symbol is found, or NULL in the case of symbols defined by shl_definesym. It is valid only if EXPORT_SYMBOLS or INITIALIZERS were requested without the NO_VALUES modifier. It is especially useful when used with the GLOBAL_VALUES modifier, allowing you to determine the library in which the most-visible definition of a symbol occurs.

shl_getsymbols Example

int show_symbols(shl_t  hndl,
                 short  type,
                 int    flags)

hndl

The handle of the shared library whose symbols you want to display.

type

The type of symbol you want to display. This is the same as the type parameter to shl_getsymbols and can have these values: TYPE_PROCEDURE, TYPE_DATA, or TYPE_UNDEFINED. If it is TYPE_UNDEFINED, show_symbols displays the type of each symbol.

flags

This is the same as the flags parameter. It can have the value EXPORT_SYMBOLS or IMPORT_SYMBOLS. In addition, it can be ORed with NO_VALUES or GLOBAL_VALUES. If EXPORT_SYMBOLS is specified without being ORed with NO_VALUES, show_symbols displays the address of each symbol.