Linker and Libraries Guide Appendix A Link-Editor Quick Reference

The following sections provide a simple overview, or cheat sheet, of the most commonly used link-editor scenarios. See Link-Editing for an introduction to the kinds of output modules generated by the link-editor.

The examples provided show the link-editor options as supplied to a compiler driver, this being the most common mechanism of invoking the link-editor. In these examples cc(1) is used. See Using a Compiler Driver.

The link-editor places no meaning on the name of any input file. Each file is opened and inspected to determine the type of processing it requires. See Input File Processing.

Shared objects that follow a naming convention of libx.so, and archive libraries that follow a naming convention of libx.a, can be input using the -l option. See Library Naming Conventions. This provides additional flexibility in allowing search paths to be specified using the -L option. See Directories Searched by the Link-Editor.

The link-editor basically operates in one of two modes, static or dynamic.

Static Mode

Static mode is selected when the -d n option is used, and enables you to create relocatable objects and static executables. Under this mode, only relocatable objects and archive libraries are acceptable forms of input. Use of the -l option results in a search for archive libraries.

Creating a Relocatable Object

• To create a relocatable object use the -d n and -r options:

$ cc -dn -r -o temp.o file1.o file2.o file3.o .....

Creating a Static Executable

The use of static executables is limited. See Static Executables. Static executables usually contain platform-specific implementation details that restricts the ability of the executable to be run on an alternative platform. Many implementations of Solaris OS libraries depend on dynamic linking capabilities, such as dlopen(3C) and dlsym(3C). See Loading Additional Objects. These capabilities are not available to static executables.

• To create a static executable use the -d n option without the -r option:

$ cc -dn -o prog file1.o file2.o file3.o .....

The -a option is available to indicate the creation of a static executable. The use of -d n without a -r implies -a.

Dynamic Mode

Dynamic mode is the default mode of operation for the link-editor. It can be enforced by specifying the -d y option, but is implied when not using the -d n option.

Under this mode, relocatable objects, shared objects and archive libraries are acceptable forms of input. Use of the -l option results in a directory search, where each directory is searched for a shared object. If no shared object is found, the same directory is then searched for an archive library. A search only for archive libraries can be enforced by using the -B static option. See Linking With a Mix of Shared Objects and Archives.

Creating a Shared Object

• To create a shared object use the -G option. -d y is optional as it is implied by default.

• Input relocatable objects should be built from position-independent code. For example, the C compiler generates position-independent code under the -K pic option. See Position-Independent Code. Use the -z text option to enforce this requirement.

• Avoid including unused relocatable objects. Or, use the -z ignore option, which instructs the link-editor to eliminate unreferenced ELF sections. See Remove Unused Material.

• If the shared object is intended for external use, make sure it uses no application registers. Not using application registers provides the external user freedom to use these registers without fear of compromising the shared object's implementation. For example, the SPARC C compiler does not use application registers under the -xregs=no%appl option.

• Establish the shared objects public interface by defining the global symbols that should be visible from the shared object, and reducing any other global symbols to local scope. This definition is provided by the -M option together with an associated mapfile. SeeAppendix B, Versioning Quick Reference.

• Use a versioned name for the shared object to allow for future upgrades. See Coordination of Versioned Filenames.

• Self-contained shared objects offer maximum flexibility. They are produced when the object expresses all dependency needs. Use the-z defs to enforce this self containment. See Generating a Shared Object Output File.

• Avoid unneeded dependencies. Use ldd with the -u option to detect and remove unneeded dependencies. See Shared Object Processing. Or, use the -z ignore option, which instructs the link-editor to record dependencies only to objects that are referenced.

• If the shared object being generated has dependencies on other shared objects, indicate they should be lazily loaded using the -z lazyload option. See Lazy Loading of Dynamic Dependencies.

• If the shared object being generated has dependencies on other shared objects, and these dependencies do not reside in the default search locations, record their path name in the output file using the -R option. See Shared Objects With Dependencies.

• Optimize relocation processing by combining relocation sections into a single .SUNW_reloc section. Use the -z combrelocoption.

• If interposing symbols are not used on this object or its dependencies, establish direct binding information with -B direct. SeeDirect Bindings.

The following example combines the above points:

$ cc -c -o foo.o -K pic -xregs=no%appl foo.c$ cc -M mapfile -G -o libfoo.so.1 -z text -z defs -B direct -z lazyload \-z combreloc -z ignore -R /home/lib foo.o -L. -lbar -lc

• If the shared object being generated is used as input to another link-edit, record within it the shared object's runtime name using the -h option. See Recording a Shared Object Name.

• Make the shared object available to the compilation environment by creating a file system link to a non-versioned shared object name. See Coordination of Versioned Filenames.

The following example combines the above points:

$ cc -M mapfile -G -o libfoo.so.1 -z text -z defs -B direct -z lazyload \-z combreloc -z ignore -R /home/lib -h libfoo.so.1 foo.o -L. -lbar -lc$ ln -s libfoo.so.1 libfoo.so

• Consider the performance implications of the shared object: Maximize shareability, as described in Maximizing Shareability: Minimize paging activity, as described in Minimizing Paging Activity: Reduce relocation overhead, especially by minimizing symbolic relocations, as described in Reducing Symbol Scope: Allow access to data through functional interfaces, as described in Copy Relocations.

Creating a Dynamic Executable

• To create a dynamic executable don't use the -G, or -d n options.

• Indicate that the dependencies of the dynamic executable should be lazily loaded using the -z lazyload option. See Lazy Loading of Dynamic Dependencies.

• Avoid unneeded dependencies. Use ldd with the -u option to detect and remove unneeded dependencies. See Shared Object Processing. Or, use the -z ignore option, which instructs the link-editor to record dependencies only to objects that are referenced.

• If the dependencies of the dynamic executable do not reside in the default search locations, record their path name in the output file using the -R option. See Directories Searched by the Runtime Linker.

• Establish direct binding information using -B direct. See Direct Bindings.

The following example combines the above points:

$ cc -o prog -R /home/lib -z ignore -z lazyload -B direct -L. \-lfoo file1.o file2.o file3.o .....