Shared libraries

Using the specification file for compatibility

The way in which directives are used in the specification file can affect compatibility across versions of a shared library. This section gives some guidelines on how to use the directives #branch, #hide, and #export (see also mkshlib(CP)).

Preserve branch table order

Add new functions only at the end of the branch table. Try and maintain compatibility with previous versions after a specification file for the library is created. New functions can be added without breaking old a.out files as long as the previous assignments are not changed. This allows distribution of a new version of the library without having to re-link all of the a.out files that used the previous version.

Use #hide and #export to limit externally visible symbols

Variables (or functions) can be referenced from several object files for inclusion in the shared library. However, they are not intended to be available to users of the shared library. They must be external so that the link editor can properly resolve all references to symbols and create the target shared library, but should be hidden from the user's view to prevent their use. Unintended use can result in compatibility problems if the symbols move or are removed between versions of the shared library.

The #hide and #export directives can resolve this dilemma. The #hide directive causes mkshlib, after resolving all references within the shared library, to alter the symbol tables of the shared library so that all specified external symbols are made static and inaccessible from user code. You can specify the symbols to be so treated either individually or through the use of regular expressions.

The #export directive allows you to specify those symbols in the range of an accompanying #hide directive regular expression that should remain external. For example, in the shared C library all data symbols are hidden by default. Symbols required outside of the library are then explicitly exported:

   #hide linker
   #export linker
   errno
   optarg
   opterr
   optind
   optopt

The advantage to this approach is that future changes to the library won't introduce new external symbols (possibly causing name collisions), unless the new symbols are explicitly exported. The symbols to be exported are chosen by looking at a list of all the current external symbols in the shared C library and finding out what each symbol is used for. The symbols that are global but were only used in the shared C library are not exported; these symbols will be hidden from applications code. All other symbols are explicitly exported.

NOTE: It is a fatal error to try to explicitly name the same symbol in a #hide and an #export directive.

The #export directive is useful when building a complicated shared library where many symbols are to be made static. In these cases, it is more efficient to use regular expressions to make all external variables static and individually list those symbols you need to be external.

NOTE: Symbols mentioned in the #branch and #init directives are services of the shared library, must be external symbols, and cannot be made static through the use of these directives.