8322 nl: misleading-indentation

[unleashed/tickless.git] / usr / src / tools / scripts / interface_check.1onbld

.\" Copyright (c) 2009, 2010, Oracle and/or its affiliates. All rights reserved.
.\"
.\" 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
.\"
.TH INTERFACE_CHECK 1ONBLD "Mar 25, 2010"
.SH NAME
interface_check \- check shared object interfaces
.SH SYNOPSIS
\fBinterface_check [-hIo] [-c vertype_module] [-E errfile] [-e exfile] [-f listfile] [-i intffile] [-w outdir] file | dir, ...\fP
.SH DESCRIPTION
The
.I 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
.B -i
option, and the interface description file created can be used with
.I 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.
.LP
.I interface_check
is typically called from \fBnightly(1ONBLD)\fP when the \fB-A\fP
option is in effect. In this case the shared objects under
the associated \fIproto\fP area (\fB$ROOT\fP) are examined.
.I interface_check
can also be run standalone against any set of dynamic objects.
.LP
.I interface_check
uses \fBelfdump(1)\fP and \fBpvs(1)\fP to
check file naming standardization, and versioning consistency. These
check are carried out for the following reasons:
.TP 4
\(bu
A shared object should exist with a versioned filename.
A versioned filename commonly takes the form of a \fI.so\fP suffix
followed by a version number. For example, \fI/usr/lib/libc.so.1\fP
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:
.sp
.RS 6
foo.so: does not have a versioned name
.RE
.TP
\(bu
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:
.sp
.RS 6
foo.so.1: no versions found
.RE
.TP
\(bu
Version definitions should follow a standard naming convention, i.e.,
\fBSUNW_\fIx.y\fP\fP, \fBSUNWprivate_\fIx.y\fP\fP, or \fIfilename\fP.  The
latter version is a base version and is used to capture any reserved
interface symbols (i.e., \fI_end\fP, \fI_etext\fP, etc.).  Any non-conforming
version names are displayed as:
.sp
.RS 6
foo.so.1: non-standard version name: \fIversion-name\fP
.RE
.sp
.RS 4
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 \fBld(1)\fP \fI-h\fP).
.RE
.TP
\(bu
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:
.sp
.RS 6
foo.so.1: scoped object contains no versions
.LP
When used with the \fI-i\fP option
.I 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.
.LP
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
.I interface_cmp.
.sp
.SH OPTIONS
.LP
The following options are supported:
.TP 4
.B \-c vertype_module
By default,
.I 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
.I interface_check
at runtime. The \fB-c\fP option can be used to supply
an alternative module, customized for a different code base, allowing
.I interface_check
to operate on code from other projects. The alternative module must
supply the same module and calling interfaces as the standard module.
.TP 4
.B \-E errfile
Direct error messages for the analyzed objects to \fIerrfile\fP instead
of stdout.
.TP 4
.B \-e exfile
An exception file is used to exclude objects from
the usual rules. See EXCEPTION FILE FORMAT.
.TP 4
.B \-f listfile
Normally,
.I interface_check
runs
.I find_elf
to locate the ELF objects to analyze. The \fB-f\fP option can be
used to instead provide a file containing the list of objects to
analyze, in the format produced by '\fBfind_elf -r\fP'.
.TP 4
.B \-h
Prevent the generation of the CDDL license and Sun copyright header
normally produced at the start of output.
.TP 4
.B \-I
When used with the \fB-i\fP 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 \fB-t\fP option to
.I interface_cmp. See INTERFACE DESCRIPTION FILE FORMAT.
.TP 4
.B \-i intffile
Produce an output file containing a complete interface definition for
the objects analyzed. This file can be used with
.I interface_cmp
to audit versioning between gates, or prior to integration within
a single gate. See INTERFACE DESCRIPTION FILE FORMAT.
.TP 4
.B \-o
Produce one-liner output, with each line of diagnostic output
prefixed with the object pathname.
.TP
.B -w outdir
Interpret the paths of all input and output files relative to \fIoutdir\fP.
.SH EXCEPTION FILE FORMAT
Exceptions to the rules enforced by
.I interface_check
are be specified using an exception file. The \fB-e\fP 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,
.I interface_check
will use
.I /opt/onbld/etc/exception_list/interface_check
as a fallback default exception file.
.P
To run
.I interface_check
without applying exceptions, specify \fB-e\fP with a value of /dev/null.
.P
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
.I interface_check.
Exceptions are specified as space separated keyword, and \fBperl(1)\fP
regular expression:
.sp
.in +4
.nf
keyword  perl-regex
.fi
.in -4
.sp
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:
.sp
.in +4
.nf
lib
lib/amd64
lib/sparcv9
.fi
.in -4
.sp
The exceptions understood by
.I interface_check
are:
.sp
.ne 2
.na
\fBNONSTD_VERNAME\fR
.ad
.RS 17n
.sp
Objects that are allowed to deviate from our standard version names.
.RE

.sp
.ne 2
.na
\fBNOVERDEF\fR
.ad
.RS 17n
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
.RE

.sp
.ne 2
.na
\fBPLUGIN\fR
.ad
.RS 17n
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.
.RE
.SH INTERFACE DESCRIPTION FILE FORMAT
When the \fB-i\fP option is used
.I interface_check
produces an \fIInterface Description File\fP that captures a description of
the interfaces provided by each ELF object processed.
.P
Unless the \fB-h\fP option is used,
.I 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.
.P
Following the header comment,
.I 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:
.sp
.in +4
.nf
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
.fi
.in -4
.sp
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.
.P
When the \fB-I\fP 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
\fB-I\fP for the above example produces the following output:
.sp
.in +4
.nf
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
.fi
.in -4
.sp
The \fB-I\fP option is primary used for debugging
.I interface_check
and
.I interface_cmp.
.SH EXAMPLES
The following example uses
.I interface_check
to generate an interface database for a workspace:
.PP
.RS
.nf
% 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
.br
.SH FILES
.LP
.RS 5
$CODEMGR_WS/exception_list/interface_check
/opt/onbld/etc/exception_list/interface_check
.SH SEE ALSO
.BR find_elf(1ONBLD),
.BR interface_cmp(1ONBLD),
.BR ld(1),
.BR ldd(1),
.BR elfdump(1),
.BR pvs(1).