JavaScript is required to for searching.
Skip Navigation Links
Exit Print View
Linker and Libraries Guide
search filter icon
search icon

Document Information


1.  Introduction to the Oracle Solaris Link Editors

2.  Link-Editor

3.  Runtime Linker

4.  Shared Objects

5.  Application Binary Interfaces and Versioning

Interface Compatibility

Internal Versioning

Creating a Version Definition

Creating a Weak Version Definition

Defining Unrelated Interfaces

Binding to a Version Definition

Verifying Versions in Additional Objects

Specifying a Version Binding

Binding to Additional Version Definitions

Redefining an Interface

Binding to a Weak Version

Version Stability

Relocatable Objects

External Versioning

Coordination of Versioned Filenames

Multiple External Versioned Files in the Same Process

6.  Support Interfaces

7.  Object File Format

8.  Thread-Local Storage

9.  Mapfiles

A.  Link-Editor Quick Reference

B.  Versioning Quick Reference

C.  Establishing Dependencies with Dynamic String Tokens

D.  Direct Bindings

E.  System V Release 4 (Version 1) Mapfiles

F.  Linker and Libraries Updates and New Features


External Versioning

Runtime references to a shared object should always refer to the versioned file name. A versioned file name is usually expressed as a file name with a version number suffix.

Should a shared object's interface changes in an incompatible manner, such a change can break old applications. In this instance, a new shared object should be distributed with a new versioned file name. In addition, the original versioned file name must still be distributed to provide the interfaces required by the old applications.

You should provide shared objects as separate versioned file names within the runtime environment when building applications over a series of software releases. You can then guarantee that the interface against which the applications were built is available for the application to bind during their execution.

The following section describes how to coordinate the binding of an interface between the compilation and runtime environments.

Coordination of Versioned Filenames

A link-edit commonly references shared object dependencies using the link-editors -l option. This option uses the link-editor's library search mechanism to locate shared objects that are prefixed with lib and suffixed with .so.

However, at runtime, any shared object dependencies should exist as a versioned file name. Instead of maintaining two distinct shared objects that follow two naming conventions, create file system links between the two file names.

For example, the shared object can be made available to the compilation environment by using a symbolic link. The compilation file name is a symbolic link to the runtime file name.

$ cc -o -G -K pic foo.c
$ ln -s
$ ls -l libfoo*
lrwxrwxrwx  1 usr grp          11 1991 ->
-rwxrwxr-x  1 usr grp        3136 1991

Either a symbolic link or hard link can be used. However, as a documentation and diagnostic aid, symbolic links are more useful.

The shared object has been generated for the runtime environment. The symbolic link, has also enabled this file's use in a compilation environment.

$ cc -o prog main.o -L. -lfoo

The link-editor processes the relocatable object main.o with the interface described by the shared object, which is found by following the symbolic link

Over a series of software releases, new versions of can be distributed with changed interfaces. The compilation environment can be constructed to use the interface that is applicable by changing the symbolic link.

$ ls -l libfoo*
lrwxrwxrwx  1 usr grp          11 1993 ->
-rwxrwxr-x  1 usr grp        3136 1991
-rwxrwxr-x  1 usr grp        3237 1992
-rwxrwxr-x  1 usr grp        3554 1993

In this example, three major versions of the shared object are available. Two versions, and, provide the dependencies for existing applications. offers the latest major release for creating and running new applications.

The use of this symbolic link mechanism solely is insufficient to coordinate the compilation shared object with a runtime versioned file name. As the example presently stands, the link-editor records in the dynamic executable prog the file name of the shared object the link-editor processes. In this case, that file name seen by the link-editor is the compilation environment file.

$ elfdump -d prog | grep libfoo
       [0]  NEEDED            0x1b7     

When the application prog is executed, the runtime linker searches for the dependency prog binds to the file to which this symbolic link is pointing.

To ensure the correct runtime name is recorded as a dependency, the shared object should be built with an soname definition. This definition identifies the shared object's runtime name. This name is used as the dependency name by any object that links against the shared object. This definition can be provided using the -h option during the creation of the shared object.

$ cc -o -G -K pic -h foo.c
$ ln -s
$ cc -o prog main.o -L. -lfoo
$ elfdump -d prog | grep libfoog
       [0]  NEEDED            0x1b7     

This symbolic link and the soname mechanism establish a robust coordination between the shared-object naming conventions of the compilation and runtime environment. The interface processed during the link-edit is accurately recorded in the output file generated. This recording ensures that the intended interface are furnished at runtime.

Multiple External Versioned Files in the Same Process

The creation of a new externally versioned shared object is a major change. Be sure you understand the complete dependencies of any processes that use a member of a family of externally versioned shared objects.

For example, an application might have a dependency on and an externally delivered object This latter object might also have a dependency on The application might be redesigned to use the new interfaces in However, the application might not change the use of the external object Depending on the scope of visibility of the implementations of that get loaded at runtime, both major versions of the file can be brought into the running process. The only reason to change the version of is to mark an incompatible change. Therefore, having both versions of the object within a process can lead to incorrect symbol binding and hence undesirable interactions.

The creation of an incompatible interface change should be avoided. Only if you have full control over the interface definition, and all of the objects that reference this definition, should an incompatible change be considered.