CDDL HEADER START
The contents of this file are subject to the terms of the
Common Development and Distribution License (the "License").
You may not use this file except in compliance with the License.
You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
or http://www.opensolaris.org/os/licensing.
See the License for the specific language governing permissions
and limitations under the License.
When distributing Covered Code, include this CDDL HEADER in each
file and include the License file at usr/src/OPENSOLARIS.LICENSE.
If applicable, add the following below this CDDL HEADER, with the
fields enclosed by brackets "[]" replaced with your own identifying
information: Portions Copyright [yyyy] [name of copyright owner]
CDDL HEADER END
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.
4 -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.
4 -d Asserts that the new interface is a direct descendant of old. If so, the following additional checks are enabled:
The top version of an inheritance chain must not increase by more than one.
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.
4 -e exfile An exception file is used to exclude objects from the usual rules. See EXCEPTION FILE FORMAT.
4 -o Produce one-liner output, with each line of diagnostic output prefixed with the object pathname.
4 -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.
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/sparcv9The 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.
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.
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.
% 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
Note: the above comparison files were doctored in order to provide the example, they do not indicate any real changes that have occurred in the associated system libraries.