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

6.  Support Interfaces

7.  Object File Format

8.  Thread-Local Storage

9.  Mapfiles

A.  Link-Editor Quick Reference

B.  Versioning Quick Reference

Naming Conventions

Defining a Shared Object's Interface

Versioning a Shared Object

Versioning an Existing (Non-versioned) Shared Object

Updating a Versioned Shared Object

Adding New Symbols

Internal Implementation Changes

New Symbols and Internal Implementation Changes

Migrating Symbols to a Standard Interface

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


Versioning a Shared Object

Having determined a shared object's available interfaces, the associated version definitions are created using a mapfile and the link-editor's -M option. See SYMBOL_SCOPE / SYMBOL_VERSION Directives for an introduction to this mapfile syntax.

The following example defines a vendor public interface in the shared object

$ cat mapfile
$mapfile_version 2
SYMBOL_VERSION SUNW_1.1 {                   # Release X.
$ cc -G -o -h -z text -M mapfile foo.c

The global symbols foo1 and foo2 are assigned to the shared object's public interface SUNW_1.1. Any other global symbols supplied from the input files are reduced to local by the auto-reduction directive “*”. See Reducing Symbol Scope.

Note - Each version definition mapfile entry should be accompanied by a comment reflecting the release or date of the update. This information helps coordinate multiple updates of a shared object, possibly by different developers, into one version definition suitable for delivery of the shared object as part of a software release.

Versioning an Existing (Non-versioned) Shared Object

Versioning an existing, non-versioned shared object requires extra care. The shared object delivered in a previous software release has made available all its global symbols for others to bind with. Although you can determine the shared object's intended interfaces, others might have discovered and bound to other symbols. Therefore, the removal of any symbols might result in an application's failure on delivery of the new versioned shared object.

The internal versioning of an existing, non-versioned shared object can be achieved if the interfaces can be determined, and applied, without breaking any existing applications. The runtime linker's debugging facilities can be useful to help verify the binding requirements of various applications. See Debugging Facility. However, this determination of existing binding requirements assumes that all users of the shared object are known.

If the binding requirements of an existing, non-versioned shared object cannot be determined, then you should create a new shared object file using a new versioned name. See Coordination of Versioned Filenames. In addition to this new shared object, the original shared object must also be delivered so as to satisfy the dependencies of any existing applications.

If the implementation of the original shared object is to be frozen, then maintaining and delivering the shared object binary might be sufficient. If, however, the original shared object might require updating then an alternative source tree from which to generate the shared object can be more applicable. Updating might be necessary through patches, or because its implementation must evolve to remain compatible with new platforms.