NAME

interface_cmp - compare shared object interface descriptions

SYNOPSIS

interface_cmp [-dot] [-e exfile] old new

DESCRIPTION

The interface_cmp command compares the interface definition files for two workspaces and reports versioning inconsistencies. Interface definition files are created by interface_check.

interface_cmp is typically called from nightly(1ONBLD) when the -A option is in effect following the creation of a new database by interface_check. To insure symbolic interface consistency between successive software releases, existing version definitions and their symbol association should remain intact. Any discrepancies between the two interface definitions are flagged as errors.

Note that version definition inheritance has the effect of causing a symbol to be viewed as existing in multiple definitions. This insures that both version definitions and their inheritance relationship are processed as part of the comparison.

OPTIONS

The following options are supported:

-c vertype_module: By default, interface_cmp is customized for the versioning conventions used by the Solaris OSnet code base. This specialized information, which includes the recognition of the SUNW_ prefix and other special names, is contained in a perl module named onbld_elfmod_vertype.pm, which is delivered with the SUNWonbld tools. This module is loaded by interface_cmp at runtime. The -c option can be used to supply an alternative module, customized for a different code base, allowing interface_cmp to operate on code from other projects. The alternative module must supply the same module and calling interfaces as the standard module.

-d: Asserts that the new interface is a direct descendant of old. If so, the following additional checks are enabled:

o: The top version of an inheritance chain must not increase by more than one.

o: The new interface must not add new empty versions. Pre-existing empty versions represent public interfaces that cannot be changed, but new ones should be removed before the product ships.

-e exfile: An exception file is used to exclude objects from the usual rules. See EXCEPTION FILE FORMAT.

-o: Produce one-liner output, with each line of diagnostic output prefixed with the object pathname.

-t: If the -t option is present, only one argument is allowed. The interface description file is parsed, and then regenerated on stdout in the same format used by the interface_check -I option. The -I output from interface_check and the output from interface_cmp -t should be identical, excluding header comments. This is a debugging feature, and not intended for general use.

EXCEPTION FILE FORMAT

Exceptions to the rules enforced by interface_cmp are specified using an exception file. The -e option is used to specify an explicit exception file. Otherwise, if used in an activated workspace, the default exception file is $CODEMGR_WS/exception_list/interface_cmp if that file exists. If not used in an activated workspace, or if $CODEMGR_WS/exception_list/interface_cmp does not exist, interface_cmp will use /opt/onbld/etc/exception_list/interface_cmp as a fallback default exception file.

To run interface_cmp without applying exceptions, specify -e with a value of /dev/null.

A '#' character at the beginning of a line, or at any point in a line when preceded by whitespace, introduces a comment. Empty lines, and lines containing only comments, are ignored by interface_cmp. Exceptions are specified as space separated keyword, and perl(1) regular expressions. The number of regular expressions depends on the particular exception in questions:

keyword perl-regex...

Since whitespace is used as a separator, the regular expression cannot itself contain whitespace. Use of the \s character class to represent whitespace within the regular expression is recommended. Before the perl regular expression is used, constructs of the form MACH(dir) are expanded into a regular expression that matches the directory given, as well as any 64-bit architecture subdirectory that might be present (i.e. amd64, sparcv9). For instance, MACH(lib) will match any of the following:

lib
lib/amd64
lib/sparcv9

The exceptions understood by interface_cmp are:

ADDSYM sym_re version_re object_re

The interfaces in a given version are not supposed to change. interface_cmp will normally issue an error if a new interface is added to a previously released version. ADDSYM is used to override this requirement. If the added symbol, version, and object match the regular expressions specified by ADDSYM, the added symbol is ignored.

DELDYM sym_re version_re object_re

Once released to the public, interfaces are required to remain available in subsequent releases. DELSYM is used to override this requirement, as can occur when interfaces are EOL'd. Such an action generally requires a PSARC case. If the deleted symbol, version, and object match the regular expressions specified by DELSYM, the deleted symbol is ignored.

EMPTY_TOPVERSION version_re object_re

interface_cmp normally issues an error if the old object has an empty top version that is non-empty in the new object. Such a situation is normally an error, but may legitimately occur as part of a fix to another versioning error. If the version, and object match the regular expressions specified by EMPTY_TOPVERSION, the error is suppressed.

EXAMPLES

The following example uses interface_cmp to compare this releases interface definition with a previous builds results:

%
interface_cmp
-d
-o
$SRC/ELF-data.$MACH.ref/interfaces \ $SRC/ELF-data.$MACH/interfaces
lib/libadm.so.1: SUNW_1.1: added interface: circf(4)
lib/libaio.so.1: SUNW_1.1: deleted interface: _aiocancel