Defining the Solaris ABI

Although the Solaris ABI is documented in the Solaris man pages, the ABI is defined in the Solaris libraries. These definitions are done by means of the library versioning technology and policies used in the link editor and run-time linker.

Symbol Versioning in Solaris Libraries

The Solaris link editor and run-time linker use two kinds of library versioning: file versioning and symbol versioning. In file versioning, a library is named with an appended version number, such as libc.so.1. When an incompatible change is made to one or more public interfaces in that library, the version number is incremented (for example, to libc.so.2). In a dynamically linked application, a symbol bound to at build time might not be present in the library at run time. In symbol versioning, the Solaris linker associates a set of symbols with a name. The linker then checks for the presence of the name in the library during run-time linking to verify the presence of the associated symbols.

Library symbol versioning associates a set of symbols with a symbol version name, and number if that name has a numbering scheme, by means of a mapfile. The following is an example mapfile for a hypothetical Sun library, libfoo.so.1.

        SUNW_1.2 {
            global:
                symbolD;
                symbolE
        } SUNW_1.1;

        SUNW_1.1 {
            global:
                symbolA;
                symbolB;
                symbolC;
        };

        SUNWprivate {
            global:
                __fooimpl;
        };

        local: *

This mapfile indicates that symbolA, symbolB, and symbolC are associated with version SUNW_1.1, symbolD and symbolE are associated with SUNW_1.2, and that SUNW_1.2 inherits all the symbols associated with SUNW_1.1. The symbol __fooimpl is associated with a different named set which does not have a numbered inheritance chain.

During build time, the link editor examines the symbols used by the application. The link editor records the set names in the application on which those symbols depend. In the case of chained sets, the link editor records the smallest named set containing all the symbols used by the application. If an application uses only symbolA and symbolB, the link editor records a dependency on SUNW_1.1. If an application uses symbolA, symbolB, and symbolD, the link editor records a dependency on SUNW_1.2, because SUNW_1.2 includes SUNW_1.1.

At run time, the linker verifies that the version names recorded as dependencies in the application are present in the libraries that are being linked. This process is a quick way to verify the presence of required symbols. For more details, see the Linker and Libraries Guide.

The "local: *" directive in the mapfile means that any symbol in the library that is not explicitly associated with a named set is scoped locally to the library. Such locally scoped symbols are not visible outside the library. This convention ensures that symbols are only visible when associated with a symbol versioning name.

Using Symbol Versioning to Label the Solaris ABI

Since all visible symbols in a library belong to some named set, the naming scheme can be used to label the symbols' ABI status. This labeling is done by associating all private interfaces with a set name beginning with SUNWprivate. Public interfaces begin with other names, specifically:

• SYSVABI, for interfaces defined by the System V ABI definition

• SISCD, for interfaces defined by the SPARC International SPARC Compliance Definition

• SUNW, for interfaces defined by Sun Microsystems

These public, named sets are numbered with a major.minor numbering scheme. The minor number is incremented as new symbols are added to the set. The major number is incremented in the rare instance when an existing symbol changes incompatibly. When an existing symbol changes incompatibly, the version number in the library's file name is also incremented.

The definition of the Solaris library ABI is therefore contained in the libraries, and consists of the set of symbols that are associated with symbol version names that do not begin with SUNWprivate. The pvs command lists the symbols in a library.