The Solaris ABI and ABI Tools
The Solaris™ Application Binary Interface (ABI) defines the interfaces available for the use of application developers. Conforming to the ABI enhances an application's binary stability. This chapter discusses the Solaris ABI and the tools provided to verify an application's compliance with the ABI, including:
The definition and purpose of the Solaris ABI, discussed in"Defining the Solaris ABI".
The usage of the two ABI tools, appcert and apptrace, discussed in "Solaris ABI Tools".
What is the Solaris ABI?
The Solaris ABI is the set of supported run-time interfaces available for an application to use with the Solaris operating environment. The most important components of the ABI are:
The interfaces provided by the Solaris system libraries (documented in section 3 of the man pages)
The interfaces provided by the Solaris kernel system calls (documented in section 2 of the man pages)
The locations and formats of various system files and directories (documented in section 4 of the man pages)
The input and output syntax and semantics of Solaris utilities (documented in section 1 of the man pages)
The main component of the Solaris ABI is the set of system library interfaces, and the term ABI in this chapter refers only to that component. The ABI contains exclusively C language interfaces, as C is the only language for which the Solaris operating environment provides interfaces.
C source code written to the Solaris API (Application Programming Interface) is transformed by the C compiler into a binary for one of three ABI versions, depending on the platform (32-bit SPARC, 64-bit SPARC, or 32-bit Intel). While the ABI is very similar to the API, the source compilation process introduces several important differences:
Compiler directives such as #define can alter or replace source-level constructs. The resulting binary may lack a symbol present in the source or include a symbol not present in the source.
The compiler may generate processor-specific symbols, such as arithmetic instructions, which augment or replace source constructs.
The compiler's binary layout may be specific to that compiler and the versions of the source language which it accepts. In such cases, identical code compiled with different compilers may produce incompatible binaries.
For these reasons, source-level (API) compatibility does not provide a sufficient expectation of binary compatibility across Solaris releases.
The Solaris ABI comprises the supported interfaces provided by the operating system. Not all the interfaces available in the system are supported for application use; some are intended for the exclusive use of the operating system. Prior to the SunOS 5.6 release, all of the interfaces in Solaris libraries were available for application developers to use. With the library symbol scoping technology available in the Solaris link editor, interfaces not intended for use outside of a library have their scope reduced to be purely local to the library (see the Linker and Libraries Guide for details). Not all private interfaces can have such a reduced scope due to system requirements. These interfaces are labeled private and are not included in the Solaris ABI.
Defining the Solaris ABI
Although the Solaris ABI is documented in the Solaris man pages, it 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 may not be present in the library at run time. In symbol versioning, the Solaris linker associates a set of symbols with a name, 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, one which does not have a numbered inheritance chain.
During build time, the link editor examines the symbols used by the application and 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 checks to see that the version names recorded as dependencies in the application are present in the libraries being linked. This is a quick way to verify the presence of required symbols. For more details, see the Linker and Libraries Guide.
Note - The "local: *" directive in the mapfile means that any symbol in the library not explicitly associated with a named set has a scope local to the library and is not visible outside it. 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, where 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, which also increments the version number in the library's file name.
The definition of the Solaris library ABI is therefore contained in the libraries themselves, and consists of the set of symbols associated with symbol version names that do not begin with SUNWprivate. The pvs command lists the symbols in a library.
Solaris ABI Tools
The Solaris operating environment provides two tools to verify that an application's use of Solaris interfaces conforms to the Solaris ABI. The appcert utility statically examines the Solaris library interfaces used by ELF binaries (executables and shared objects) for private interface usage. The appcert utility then produces summary and detailed reports of any potential binary stability problems it finds. The apptrace tool uses the link-auditing functionality of the run-time linker to dynamically trace Solaris library routine calls as the application runs. This enables developers to examine an application's use of the Solaris system interfaces.
The ABI tools enable easy and rapid identification of binaries that may have binary compatibility problems with a given Solaris release. To check binary stability:
Use appcert on the current Solaris release for triage. This identifies which binaries use problematic interfaces and which do not.
Use apptrace on the target Solaris release for verification. This verifies whether there are interface compatibility problems by enabling dynamic observation of those interfaces as they are used.