OpenSolaris

BestPractice

• Applies to All shared objects intended to be used with Solaris.
• Authority SAC
• Approval PSARC 2002/300
• Effective Solaris 2.5.1
• Policy All shared objects intended for use on Solaris, whether or not they are delivered as a part of Solaris, or unbundled, must follow the rules enumerated below. In addition, it is strongly advised that the shared objects be free of any of the warnings.
• Details 
   Definitions:

Errors

• • E1 Version definitions must follow a standard naming convention.
     The convention for Solaris Engineers to use for Solaris ABI interface naming is as follows:
    • SUNW_m.n.o Public interface versioning
    • SUNWprivate_m.n Private interface versioning
       (where m is the major number, n is the minor number, and o is an optional micro number)
    • SUNWprivate
    • base version name
      base version name
       In addition, note that non-conforming base version names are often generated by accident when the file itself has an internal identification that differs from the actual filename (See ld(1) -h option for details).
       An example would be a file called nss_files.so.1 in the filesystem, that asserts via its SONAME that it will be called libnss_files.so.1 at runtime. The pvs -s and elfdump -d commands can also be used to identify this problem.
       A convention for other ABI interface naming would need to use some other naming convention. SUNW* names only apply today to the Solaris ABI.
       Note that the Reserved version definition names
    • SYSVABI_1.[2|3] and
    • SISCD_2.3[a|b] define industry standard interfaces in the System V Interface Definition and the Sparc Compliance Definition, and must not be used for other interfaces. In particular, be careful to not inadvertantly copy/paste these symbols/versions into new libraries where they don't belong.
  • E2 A proper inheritance chain must be maintained.
     Version inheritance is tracked through the versions file under the spec/ subdirectory (See README.spec for details). If a subsequent version set is not incremented properly (i.e., it increments by more that .1 per release of a library), then this results in a malformed inheritance chain. Errors made in the inheritance chain prior to 1.1 will be ignored by intf_check for historical purposes. (See pvs(1) -d option for details).
  • E3 Public symbols must not be scoped local or removed from a library.
     A shared object delivered in a previous software release has made available all its global symbols for others to bind with. Therefore, if a public symbol is removed or scoped local on the current release, applications depending on the removed public interface will break.
  • E4 Public symbols must not be demoted to private.
     This is a dangerous practice since a committed public interface has become unusable/unstable.
  • E5 A new symbol must be assigned to the highest version name of its library.
     A version definition exists to allow tracking of all intended interfaces offered in a given release of the library. Once the integrity of these version definitions are broken, users of the shared object can no longer track interfaces offered on each software release. Therefore, new symbols must be assigned to the current minor release-level of the library. For new libraries, Public interface versioning begins with SUNW_1.1 while Private interface versioning must be SUNWprivate. If the library already has Private interfaces, they may have numbered version names like SUNWprivate_m.n. If so, just use the highest numbered private version name for the new interface.
  • E6 A symbol must remain assigned to the same version throughout the life of the library.
     This version indicates when the symbol was first introduced. If the interface is reassigned to a different version on another release, its history and availability information is lost.
  • E7 The highest version number of a library must not be incremented by more than ".1" between releases.
     Since each version definition indicates the interfaces applied to each software release, no more than one version definition should be specified per release of a library. Note that the major revision number is incremented whenever an incompatible change is made to an interface. This could be the case if an API changes so dramatically as to invalidate dependencies. This is expected to rarely occur in practice. Also note that micro version numbers are used as a means of managing the inclusion of a subset of an existing version into a micro release (i.e., update release, feature patch...) When these subset interfaces are introduced to a micro release, the symbol version is incremented by a micro number [m.n.(o++)]
     When release N+1 is frozen (at which time it is expected that no more update releases for release N will be produced), the micro versions of "N" must be inherited by the "N+1" release.
     For example; the "versions" file for minor release "N+1" to reflect its inclusion of micro release(s) (i.e., m.n.o) will look like the following:

Warnings

• • W1  A shared object should exist with a versioned filename.
     A versioned filename commonly takes the form of a .so suffix followed by a version number. For example, /usr/lib/libc.so.1 is the shared object representation of version one of the standard C library made available to the runtime environment. A versioned filename allows for a change in the exported interface of the shared object over a series of software releases.
  • W2  A shared object containing a public interface should have an associated compilation environment name and a SONAME recorded.
     Given that a file does exist as a versioned filename, a compilation environment filename must also exist if the shared object offers any public interfaces. This compilation environment name is typically established as a symbolic link to the latest versioned filename. In the compilation environment, this name provides for processing by the link-editor (ld(1) using the -l option, and takes the form of a lib prefix and .so suffix.). For example, libc.so exists as a compilation symlink for the versioned filename libc.so.1.
  • W3  A shared object containing only private interfaces should not deliver an associated compilation environment name.
    Note that it may be the case that a compilation environment name exists to simplify the building of other components, however if the versioned filename does not provide a public interface, a compilation environment name may not be required to be provided to external users. Note, if a compilation environment name does exist its SONAME must be recorded.
    NOTE that this check generates an informational WARNING since we do not know whether the compilation environment name will be delivered. Our tool can only check at the level of the build time in the $ROOT area. Since we do not yet check against a package database yet, this is at best, a heuristic that the compilation symlink is getting delivered with the library.
    NOTE that one instance in which a shared object containing only private interfaces may deliver an associated compilation environment name (and related materials, such as lint libraries and header files) is when the interfaces are to be used by a non-product (likely testing-related) delivery as part of the same project. The existence of such cases is the reason why this rule is just a warning. Databases that need to reference this exception case may refer to 'PSARC 2005/430' without requiring additional ARC review.
    NOTE that any human-readable files (e.g., include files) with private interfaces that can accept comments should have a warning against casual use of those interfaces. However, it is not ARC policy to require any ad-hoc obscuring of interfaces, such as symbol renaming or non-"lib" prefixes, unless a generic scoping mechanism is employed.
  • W4  A shared object should contain interfaces that are versioned.
     Versions should be defined within a shared object both to clarify its public or private use, and to explicitly define the interfaces that it makes available. The reduction in object size, and relocation cost created by reducing non-interface symbols to locals is an added bonus.
  • W5  Version definitions should offer at least one interface.
     Note there exist some legitimate uses of empty version definitions, as interfaces have been regrouped, and old version definitions must exist to insure backward compatibility. However other empty interface definitions are typically the result of cut-and-paste use within spec files.
  • W6  Private symbols should not be removed or scoped local to a library without careful analysis of dependencies on these interfaces.
     Review of your contracts with those who depend on these private interfaces is advised before changing any symbols.
  • W7  A new Public symbol should have a corresponding manpage and a 3lib manpage entry.
     If no documentation is available for the interface (i.e., the interface is meant to be private), then this interface should be labeled as SUNWprivate.
  • W8  A committed private (one that is not exposed for use, but is intended to remain stable) interface should not be promoted to public if the transition involves signature changes.
     ARC approval is needed to allow such a change.
    NOTE that this is an informational WARNING and is not currently turned on in the tool by default. It is checked here primarily for those interested in tracking interface transitions in update releases. A committed private interface transitioning to public (with a signature change) in an update release can break binary compability, so it should be flagged. However, we have no current method of tracking signature changes with this tool. Therefore, this checking is an option that can be turned on by the individual developers.

Implementation
 This is a heads up that we have developed an ABI auditing tool which enables Gatekeepers to detect ABI errors immediately as they enter the gate.
 In the past, we have found that the most common cause of ABI breakage in the gate has been a lack of understanding the importance of binary compatibility and to a greater extent, the versioning policies that enforce it. This project attempts to not only educate shared object developers and other maintainers of the Solaris ABI by clearly defining the policies and rules in the manpage, but also to provide a tool to detect errors in the gate as they occur.
 By arming gatekeepers with this tool, we hope that future breakage in the Solaris ABI can be prevented early on in the development cycle before these errors creep into the product. Currently, we have been running our tool against the on81-gate and the on10-gate, and have already found some alarming errors in the Solaris ABI. (e.g. See bugids 4646563 4420588 etc).
 Our tool will be integrated into the SUNWonbld package (as soon as the public build machines can be updated with the newest set of tools). Once integrated, gatekeepers will be able to easily track the ABI through the "-A" flag in the nightly script.
 -Boris C and Becky C
 Solaris ABI Program

Conformance

Appeals

CaseHistory

ManPages

References
Linkers and Libraries Guide