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_check is typically called from nightly(1ONBLD) when the -A option is in effect. In this case the shared objects under the associated proto area ($ROOT) are examined. interface_check can also be run standalone against any set of dynamic objects.
interface_check uses elfdump(1) and pvs(1) to check file naming standardization, and versioning consistency. These check are carried out for the following reasons:
4 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. A shared object that doesn't exist as a versioned filename is displayed as:
foo.so: does not have a versioned name
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. A non-versioned shared object is displayed as:
foo.so.1: no versions found
Version definitions should follow a standard naming convention, i.e., SUNW_x.y, SUNWprivate_x.y, or filename. The latter version is a base version and is used to capture any reserved interface symbols (i.e., _end, _etext, etc.). Any non-conforming version names are displayed as:
foo.so.1: non-standard version name: version-name
Note, that non-conforming base version names are often generated when the file itself has an internal identification that differs from the actual filename (see ld(1) -h).
A scoped object, one that has defined its external interfaces and whose internal interfaces have been reduced to locals, but has no version definitions assigned, does not inform users of the commitment level of the interfaces it offers. Scoped objects are displayed as:
foo.so.1: scoped object contains no versions
When used with the -i option interface_check produces a more detailed breakdown of a shared objects versioning. This interface description file provides for the release-to-release auditing of interfaces, and monitoring the evolution of the share objects interfaces.
These files provide a complete cross reference of version to interface relationships and are the basis for auditing a shared objects interfaces from release-to-release. Any addition, deletion or regrouping of versioning information can be detected by inspecting this database with interface_cmp.
The following options are supported:
4 -c vertype_module By default, interface_check 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_check at runtime. The -c option can be used to supply an alternative module, customized for a different code base, allowing interface_check to operate on code from other projects. The alternative module must supply the same module and calling interfaces as the standard module.
4 -E errfile Direct error messages for the analyzed objects to errfile instead of stdout.
4 -e exfile An exception file is used to exclude objects from the usual rules. See EXCEPTION FILE FORMAT.
4 -f listfile Normally, interface_check runs find_elf to locate the ELF objects to analyze. The -f option can be used to instead provide a file containing the list of objects to analyze, in the format produced by 'find_elf -r'.
4 -h Prevent the generation of the CDDL license and Sun copyright header normally produced at the start of output.
4 -I When used with the -i option, the interface definition produced shows expanded symbol inheritance. Each version lists the symbols inherited from sub-versions. This mode is primarily of interest for debugging, as it matches the format produced by the -t option to interface_cmp. See INTERFACE DESCRIPTION FILE FORMAT.
4 -i intffile Produce an output file containing a complete interface definition for the objects analyzed. This file can be used with interface_cmp to audit versioning between gates, or prior to integration within a single gate. See INTERFACE DESCRIPTION FILE FORMAT.
4 -o Produce one-liner output, with each line of diagnostic output prefixed with the object pathname.
-w outdir Interpret the paths of all input and output files relative to outdir.
To run interface_check 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_check. Exceptions are specified as space separated keyword, and perl(1) regular expression:
keyword perl-regexSince 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_check are: NONSTD_VERNAME
Objects that are allowed to deviate from our standard version names.
Objects that are not expected to contain versioning information. Note that PLUGIN objects are automatically exempt from this, so these directives are generally applied to non-plugin objects
Sharable objects underneath these parts of the tree are taken to be plugins. Plugins are not required to have versioned file names, and are not required to be internally versioned.
Unless the -h option is used, interface_check produces a header comment at the start of this file, containing a CDDL block and a Sun copyright notice. The header uses '#' as a comment character for the lines containing text, and also includes empty lines.
Following the header comment, interface_check produces a description of the interfaces provided by each object. The description of each object starts with an OBJECT directive, and follows the form shown below, using /lib/amd64/libadm.so.1 as an example:
OBJECT lib/amd64/libadm.so.1 CLASS ELFCLASS64 TYPE ET_DYN ALIAS lib/64/libadm.so ALIAS lib/64/libadm.so.1 ALIAS lib/amd64/libadm.so ALIAS usr/lib/64/libadm.so ALIAS usr/lib/64/libadm.so.1 ALIAS usr/lib/amd64/libadm.so ALIAS usr/lib/amd64/libadm.so.1 TOP_VERSION SUNW_1.2 {SUNW_1.1} SYMBOL read_extvtoc SYMBOL write_extvtoc VERSION SUNW_1.1 {SUNW_0.7} VERSION SUNW_0.7 SYMBOL pkgdir SYMBOL read_vtoc SYMBOL write_vtocThe description for every object starts with OBJECT, CLASS, and TYPE directives. Following that come ALIAS lines for every alternative name by which this object is known. Every version exported by the object is designated by a VERSION or TOP_VERSION directive. A TOP_VERSION is a version at the top of the version inheritance chain, and VERSION is used for versions lower in the chain. Inherited versions are shown within {} brackets following the version name. Following each version directive are SYMBOL directives, each describing a symbol defined by that version.
When the -I option is used, version inheritance is expanded, such that each version includes the symbols inherited from sub-versions. In this mode, the SYMBOL directive is replaced with NEW for symbols defined in the version, and INHERIT for those that are inherited. Using -I for the above example produces the following output:
OBJECT lib/amd64/libadm.so.1 CLASS ELFCLASS64 TYPE ET_DYN ALIAS lib/64/libadm.so ALIAS lib/64/libadm.so.1 ALIAS lib/amd64/libadm.so ALIAS usr/lib/64/libadm.so ALIAS usr/lib/64/libadm.so.1 ALIAS usr/lib/amd64/libadm.so ALIAS usr/lib/amd64/libadm.so.1 TOP_VERSION SUNW_1.2 {SUNW_1.1} INHERIT pkgdir NEW read_extvtoc INHERIT read_vtoc NEW write_extvtoc INHERIT write_vtoc VERSION SUNW_1.1 {SUNW_0.7} INHERIT pkgdir INHERIT read_vtoc INHERIT write_vtoc VERSION SUNW_0.7 NEW pkgdir NEW read_vtoc NEW write_vtocThe -I option is primary used for debugging interface_check and interface_cmp.
% mkdir $SRC/ELF-data.$MACH % interface_check -w $SRC/ELF-data.$MACH -E interface.err -i interface $ROOT % ls -1R $SRC/ELF interface interface.err
FILES
$CODEMGR_WS/exception_list/interface_check /opt/onbld/etc/exception_list/interface_check
SEE ALSOfind_elf(1ONBLD), interface_cmp(1ONBLD), ld(1), ldd(1), elfdump(1), pvs(1).