INTERFACE_CHECK(1ONBLD)

illumos Build Tools

INTERFACE_CHECK(1ONBLD)

NAME

interface_check - check shared object interfaces

SYNOPSIS

interface_check [-hIo] [-c vertype_module] [-E errfile] [-e exfile] [-f listfile] [-i intffile] [-w outdir] file | dir, ...

DESCRIPTION

The interface_check command attempts to check a number of ELF versioning attributes for consistency with common build rules and practices. In addition, a complete breakdown of the file's version definitions can be captured using the -i option, and the interface description file created can be used with interface_cmp to audit the versioning evolution of a software product. These interface description files reflect the association of the shared object's global symbols with recorded version definitions.

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:

•: 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.

OPTIONS

The following options are supported:

-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.

-E errfile: Direct error messages for the analyzed objects to errfile instead of stdout.

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

-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'.

-h: Prevent the generation of the CDDL license and Sun copyright header normally produced at the start of output.

-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.

-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.

-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.

EXCEPTION FILE FORMAT

Exceptions to the rules enforced by interface_check are be 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_check if that file exists. If not used in an activated workspace, or if $CODEMGR_WS/exception_list/interface_check does not exist, interface_check will use /opt/onbld/etc/exception_list/interface_check as a fallback default exception file.

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-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_check are:

NONSTD_VERNAME

Objects that are allowed to deviate from our standard version names.

NOVERDEF

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

PLUGIN

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.

INTERFACE DESCRIPTION FILE FORMAT

When the -i option is used interface_check produces an Interface Description File that captures a description of the interfaces provided by each ELF object processed.

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_vtoc

The 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_vtoc

The -I option is primary used for debugging interface_check and interface_cmp.

EXAMPLES

The following example uses interface_check to generate an interface database for a workspace:

% 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