Using Linker commands

The LPATH environment variable allows you to specify which directories ld should search. If LPATH is not set, ld searches the default directory /usr/lib. If LPATH is set, ld searches only the directories specified in LPATH; the default directories are not searched unless they are specified in 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 

The -L option to ld also allows you to add additional directories to the search path. If -L libpath is specified, ld searches the libpath directory before the default places.

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

Multiple -L options can be specified. For example, to search /usr/contrib/lib and /usr/local/lib before the default places:

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

If LPATH is set, then the -L option specifies the directories to search before the directories specified in LPATH.

To force immediate binding, link an application with the -B immediate linker option. For example, to force immediate binding of all symbols in the main program and in all shared libraries linked with it, you could use this ld command:

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

The linker also supports nonfatal binding, which is useful with the -B immediate option. Like immediate binding, nonfatal immediate binding causes all required symbols to be bound at program startup. The main difference from immediate binding is that program execution continues even if the dynamic loader cannot resolve symbols. Compare this with immediate binding, where unresolved symbols cause the program to abort.

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

Note that the -B nonfatal modifier does not work with deferred binding because a symbol must have been bound by the time a program actually references or calls it. A program attempting to call or access a nonexistent symbol is a fatal error.

The linker also supports restricted binding, which is useful with the -B deferred and -B nonfatal options. The -B restricted option causes the dynamic loader to restrict the search for symbols to those that were visible when the library was loaded. If the dynamic loader cannot find a symbol within the restricted set, a run-time symbol binding error occurs and the program aborts.

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:

If such a program is linked with -B immediate, references to symbols will be bound at program startup, regardless of whether duplicate symbols are created later by shl_load or shl_definesym.

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.

For example, to optimize the call path between procedures when building a shared library called lib1.sl, use -B symbolic as follows:

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

	NOTE: The +e option overrides the -B symbolic option. For example, you use +e symbol, only symbol is exported and all other symbols are hidden. Similarly, if you use +ee symbol, only symbol is exported, but other symbols exported by default remain visible. Since all internal calls inside the shared library are resolved inside the shared library, user-supplied modules with the same name are not seen by routines inside the library. For example, you could not replace internal libc.sl malloc() calls with your own version of malloc() if libc.sl was linked with -B symbolic.

Similar to the -h (hide symbol) and +e (export symbol) linker options, -B symbolic optimizes call paths in a shared library. However, unlike -h and +e, all functions in a shared library linked with -B symbolic are also visible outside of the shared library.

Case 1: Building a Shared Library with -B symbolic

Suppose you have two functions to place in a shared library. The convert_rtn() calls gal_to_liter().

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

2. 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 3-1 shows that a direct call path is established between convert_rtn() and gal_to_liter() inside the shared library. Both symbols are visible to outside callers.

Figure 3-1 Symbols inside a Shared Library Visible with -B symbolic

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

The -h (hide symbol) and +e (export symbol) options can also optimize the call path in a shared library for symbols that are explicitly hidden. However, only the exported symbols are visible outside of the shared library.

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

or export the convert_rtn symbol:

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

In both cases, main2 will not be able to resolve its reference to gal_to_liter() because only the convert_rtn() symbol is exported as shown below:

The -a option tells the linker what kind of library to link with. It applies to all libraries (-l options) until the end of the command line or until the next -a option. Its syntax is:

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

The different option settings are:

The -a shared and -a archive options specify only one type of library to use. An error results if that type is not found. The other three options specify a preferred type of library and an alternate type of library if the preferred type is not found.

	CAUTION: You should avoid mixing shared libraries and archive libraries in the same application. For more information see “Caution When Mixing Shared and Archive Libraries ”.

The following command links with the archive versions of libcurses, libm and libc:

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

The implementation details of dynamic linking vary across platforms. To load an object module into the address space of a running program, and to be able to access its procedures and data, follow these steps on all HP9000 computers:

To illustrate dynamic linking concepts, this section presents an example program, dynprog. This program loads an object module named dynobj.o, which is created by dynamically linking two object files file1.o and file2.o (see “file1.o and file2.o ”).

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

Before seeing the program's source code, it may help to see how the program and the various object files were built. The following shows the makefile used to generate the various files.

Example 3-1 Makefile Used to Create Dynamic Link Files

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

This makefile assumes that the following files are found in the current directory:

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.

To create the executable program dynprog from this makefile, you would simply run:

$ 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

Note that the line CFLAGS = causes any C files to be compiled in ANSI mode (-Aa) and causes the compiler to search for routines that are defined in the Posix standard (-D_POSIX_SOURCE).

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

Source for dynprog

Here is the source file for the dynprog program.

Example 3-2 dynprog.c — Example Dynamic Link and Load Program

#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

Example 3-3 “Source for file1.c and file2.c” shows the source for file1.o and file2.o. Notice that foo and bar call glorp in dynprog.c. Also, both functions update the variable counter in file2.o; however, foo updates counter through the pointer (counter_ptr) defined in dynprog.c.

Example 3-3 Source for file1.c and file2.c

/**************************************************************** * 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

Now that you see how the main program and the module it loads are organized, here is the output produced when dynprog runs:

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

dynload.c

The dynload.c file contains the definitions of the functions alloc_load_space and dyn_load. Example 3-4 “Include Directives for dynload.c ” shows the #include directives must appear at the start of this file.

Example 3-4 Include Directives for 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

The alloc_load_space function returns a pointer to space (allocated by malloc) into which dynprog will load the object module dynobj.o. It syntax is:

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 by dynamically linked and loaded by base_prog.

As described in Step 1 in “Overview of Dynamic Linking ” at the start of this section, you can either guess at how much space will be required to load a module, or you can try to be more accurate. The advantage of the former approach is that it is much easier and probably adequate in most cases; the advantage of the latter is that it results in less memory fragmentation and could be a better approach if you have multiple modules to load throughout the course of program execution.

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:

1. Pre-link the specified obj_files to create base_prog.

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

3. 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.)

Example 3-5 “C Source for alloc_load_space Function ” shows the source for this function.

Example 3-5 C Source for alloc_load_space Function

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

The dyn_load function dynamically links and loads an object module into the space allocated by the alloc_load_space function. In addition, it returns the address of the entry point in the loaded module. Its syntax is:

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

The base_prog, obj_files, and dest_file parameters are the same parameters supplied to alloc_load_space. The addr parameter is the address returned by alloc_load_space, and the entry_pt parameter specifies a symbol name that you want to act as the entry point in the module.

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

1. 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 -R addr option. The name of the entry point for the file is specified with -e entry_pt.

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

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

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

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

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

Example 3-6 C Source for 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) { 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

Since there is no existing routine to flush text from the data cache before execution, you must create one. Below is the assembly language source for such a function.

Example 3-7 Assembly Language Source for 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

Suppose you want to build a shared library from an object file that contains the following symbol definitions as displayed by the nm command:

$ 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

In this example, check_sem_val, foo, bar, and sem are all global definitions. To create a shared library where check_sem_val is a hidden, local definition, you could use either of the following commands:

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

In contrast, suppose you want to export only the check_sem_val symbol. Either of the following commands would work:

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

How do you decide whether to use -h or +e? In general, use -h if you simply want to hide a few symbols. And use +e if you want to export a few symbols and hide a large number of symbols.

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.

Suppose you want to build a shared library from an object file that contains the following symbol definitions as displayed by the nm command:

$ 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

In this example, check_sem_val, foo, bar, and sem are all global definitions. To create a shared library where check_sem_val is a hidden, local definition, you could do the following:

$ ld -b -h check_sem_val sem.o

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.

When building a shared library, you might want to hide a symbol in the library for several reasons:

Exporting a symbol is necessary if the symbol must be accessible outside the shared library. But remember that, by default, most symbols are global definitions anyway, so it is seldom necessary to explicitly export symbols. In C, all functions and global variables that are not explicitly declared as static have global definitions, while static functions and variables have local definitions. In FORTRAN, global definitions are generated for all subroutines, functions, and initialized common blocks.

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.

The -r option combines multiple .o files, creating a single .o file. The reasons for hiding symbols in a .o file are the same as the reasons listed above for shared libraries. However, a performance improvement will occur only if the resulting .o file is later linked into a shared library.

By default, the linker exports all of a program's global definitions that are imported by shared libraries specified on the linker command line. For example, given the following linker command, all global symbols in crt0.o and prog.o that are referenced by libm or libc are automatically exported:

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

With libraries that are explicitly loaded with shl_load, this behavior may not always be sufficient because the linker does not search explicitly loaded libraries (they aren't even present on the command line). You can work around this using the -E or +e linker option.

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

When using +e, be sure to export any data symbols defined in the program that may also be defined in explicitly loaded libraries. If a data symbol that a shared library imports is not exported from the program file, the program uses its own copy while the shared library uses a different copy if a definition exists outside the program file. In such cases, a shared library might update a global variable needed by the program, but the program would never see the change because it would be referencing its own copy.

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.

The syntax of the +b option is

+b path_list

where path_list is the list of directories you want the dynamic loader to search at run time. For example, the following linker command causes the path .:/app/lib:: to be stored in the executable. At run time, the dynamic loader would search for libfoo.sl, libm.sl, and libc.sl in the current working directory (.), the directory /app/lib, and lastly in the location in which the libraries were found at link time (::):

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

If path_list is only a single colon, the linker constructs a path list consisting of all the directories specified by -L, followed by all the directories specified by the LPATH environment variable. For instance, the following linker command records the path list as /app/lib:/tmp:

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

Whether specified as a parameter to +b or set as the value of the SHLIB_PATH environment variable, the path list is simply one or more path names separated by colons (:), just like the syntax of the PATH environment variable. An optional colon can appear at the start and end of the 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.

When a program is linked with +s, the dynamic loader will get the library path list from the SHLIB_PATH environment variable at run time. This is especially useful for application developers who don't know where the libraries will reside at run time. In such cases, they can have the user or an install script set SHLIB_PATH to the correct value.

When writing programs that call routines not found in the default libraries linked at compile time, you must specify the libraries on the compiler command line with the -lx option. For example, if you write a C program that calls POSIX math functions, you must link with libm.

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

The linker searches libraries in the order in which they are specified on the command line (that is, the link order). In addition, libraries specified with -l are searched before the libraries that the compiler links by default.

The -l: option works just like the -l option with one major difference: -l: allows you to specify the full basename of the library to link with. For instance, -l:libm.a causes the linker to link with the archive library /usr/lib/libm.a, regardless of whether -a shared was specified previously on the linker command line.

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.

For example, even if LDOPTS were set to -a shared, the following command would link with the archive libfoo.a in the directory /usr/mylibs, the archive libm.a and libc.a:

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