usr/src/tools/scripts/interface_cmp.1

   1 .\" Copyright (c) 2009, 2010, Oracle and/or its affiliates. All rights reserved.
   2 .\"
   3 .\" CDDL HEADER START
   4 .\"
   5 .\" The contents of this file are subject to the terms of the
   6 .\" Common Development and Distribution License (the "License").
   7 .\" You may not use this file except in compliance with the License.
   8 .\"
   9 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  10 .\" or http://www.opensolaris.org/os/licensing.
  11 .\" See the License for the specific language governing permissions
  12 .\" and limitations under the License.
  13 .\"
  14 .\" When distributing Covered Code, include this CDDL HEADER in each
  15 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  16 .\" If applicable, add the following below this CDDL HEADER, with the
  17 .\" fields enclosed by brackets "[]" replaced with your own identifying
  18 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  19 .\"
  20 .\" CDDL HEADER END
  21 .\"
  22 .TH INTERFACE_CMP 1ONBLD "Mar 25, 2010"
  23 .SH NAME
  24 interface_cmp \- compare shared object interface descriptions
  25 .SH SYNOPSIS
  26 \fBinterface_cmp [-dot] [-e exfile] old new\fP
  27 .SH DESCRIPTION
  28 The
  29 .I interface_cmp
  30 command compares the interface definition files for two workspaces
  31 and reports versioning inconsistencies. Interface definition
  32 files are created by
  33 .IR interface_check.
  34 .PP
  35 .I interface_cmp
  36 is typically called from \fBnightly(1ONBLD)\fP when the \fB-A\fP
  37 option is in effect following the creation of a new database by
  38 .IR interface_check .
  39 To insure symbolic
  40 interface consistency between successive software releases, existing
  41 version definitions and their symbol association should remain intact.
  42 Any discrepancies between the two interface definitions are flagged as
  43 errors.
  44 .PP
  45 Note that version definition inheritance has the effect of causing a
  46 symbol to be viewed as existing in multiple definitions. This insures
  47 that both version definitions and their inheritance relationship are
  48 processed as part of the comparison.
  49 .SH OPTIONS
  50 The following options are supported:
  51 .TP 4
  52 .B \-c vertype_module
  53 By default,
  54 .I interface_cmp
  55 is customized for the versioning conventions used by the Solaris
  56 OSnet code base. This specialized information, which includes
  57 the recognition of the SUNW_ prefix and other special names, is
  58 contained in a perl module named onbld_elfmod_vertype.pm, which
  59 is delivered with the SUNWonbld tools. This module is loaded by
  60 .I interface_cmp
  61 at runtime. The \fB-c\fP option can be used to supply
  62 an alternative module, customized for a different code base, allowing
  63 .I interface_cmp
  64 to operate on code from other projects. The alternative module must
  65 supply the same module and calling interfaces as the standard module.
  66 .TP 4
  67 .B \-d
  68 Asserts that the \fBnew\fP interface is a direct descendant of
  69 \fBold\fP. If so, the following additional checks are enabled:
  70 .RS +4
  71 .TP
  72 .ie t \(bu
  73 .el o
  74 The top version of an inheritance chain must not increase
  75 by more than one.
  76 .RE
  77 .RS +4
  78 .TP
  79 .ie t \(bu
  80 .el o
  81 The new interface must not add new empty versions. Pre-existing empty
  82 versions represent public interfaces that cannot be changed, but new
  83 ones should be removed before the product ships.
  84 .RE
  85 .sp
  86 .TP 4
  87 .B \-e exfile
  88 An exception file is used to exclude objects from
  89 the usual rules. See EXCEPTION FILE FORMAT.
  90 .TP 4
  91 .B \-o
  92 Produce one-liner output, with each line of diagnostic output
  93 prefixed with the object pathname.
  94 .TP 4
  95 .B \-t
  96 If the \fB-t\fP option is present, only one argument is allowed.
  97 The interface description file is parsed, and then regenerated on
  98 stdout in the same format used by the
  99 .I interface_check
 100 \fB-I\fP option. The \fB-I\fP output from
 101 .I interface_check
 102 and the output from
 103 .I interface_cmp
 104 \fB-t\fP
 105 should be identical, excluding header comments.
 106 This is a debugging feature, and not intended for general use.
 107 .SH EXCEPTION FILE FORMAT
 108 Exceptions to the rules enforced by
 109 .I interface_cmp
 110 are specified using an exception file. The \fB-e\fP option is used to
 111 specify an explicit exception file. Otherwise, if used in an activated
 112 workspace, the default exception file is
 113 $SRCTOP/exception_list/interface_cmp
 114 if that file exists. If not used in an activated workspace, or if
 115 $SRCTOP/exception_list/interface_cmp does not exist,
 116 .I interface_cmp
 117 will use
 118 .I /opt/onbld/etc/exception_list/interface_cmp
 119 as a fallback default exception file.
 120 .P
 121 To run
 122 .I interface_cmp
 123 without applying exceptions, specify \fB-e\fP with a value of /dev/null.
 124 .P
 125 A '#' character at the beginning of a line, or at any point in
 126 a line when preceded by whitespace, introduces a comment. Empty lines,
 127 and lines containing only comments, are ignored by
 128 .I interface_cmp.
 129 Exceptions are specified as space separated keyword, and \fBperl(1)\fP
 130 regular expressions. The number of regular expressions depends on the
 131 particular exception in questions:
 132 .sp
 133 .in +4
 134 .nf
 135 keyword  perl-regex...
 136 .fi
 137 .in -4
 138 .sp
 139 Since whitespace is used as a separator, the regular
 140 expression cannot itself contain whitespace. Use of the \\s character
 141 class to represent whitespace within the regular expression is recommended.
 142 Before the perl regular expression is used, constructs of the form
 143 MACH(dir) are expanded into a regular expression that matches the directory
 144 given, as well as any 64-bit architecture subdirectory that
 145 might be present (i.e. amd64, sparcv9). For instance, MACH(lib) will
 146 match any of the following:
 147 .sp
 148 .in +4
 149 .nf
 150 lib
 151 lib/amd64
 152 lib/sparcv9
 153 .fi
 154 .in -4
 155 .sp
 156 The exceptions understood by
 157 .I interface_cmp
 158 are:
 159 .sp
 160 .ne 2
 161 .na
 162 \fBADDSYM\fR sym_re version_re object_re
 163 .ad
 164 .RS 17n
 165 .sp
 166 The interfaces in a given version are not supposed to change.
 167 .I interface_cmp
 168 will normally issue an error if a new interface is added to a previously
 169 released version. ADDSYM is used to override this
 170 requirement. If the added symbol, version, and object match
 171 the regular expressions specified by ADDSYM, the added symbol is ignored.
 172 .RE
 173
 174 .sp
 175 .ne 2
 176 .na
 177 \fBDELDYM\fR sym_re version_re object_re
 178 .ad
 179 .RS 17n
 180 .sp
 181 Once released to the public, interfaces are required to remain available
 182 in subsequent releases. DELSYM is used to override this
 183 requirement, as can occur when interfaces are EOL'd. Such an action generally
 184 requires a PSARC case. If the deleted symbol, version, and object match
 185 the regular expressions specified by DELSYM, the deleted symbol is ignored.
 186 .RE
 187
 188 .sp
 189 .ne 2
 190 .na
 191 \fBEMPTY_TOPVERSION\fR version_re object_re
 192 .ad
 193 .RS 17n
 194 .sp
 195 .I
 196 interface_cmp
 197 normally issues an error if the old object has an empty top version
 198 that is non-empty in the new object. Such a situation is normally
 199 an error, but may legitimately occur as part of a fix to another versioning
 200 error.  If the version, and object match
 201 the regular expressions specified by EMPTY_TOPVERSION, the error is suppressed.
 202 .RE
 203
 204 .SH EXAMPLES
 205 The following example uses
 206 .I interface_cmp
 207 to compare this releases interface definition with a previous
 208 builds results:
 209 .PP
 210 .RS
 211 .nf
 212 .B % interface_cmp -d -o $SRC/ELF-data.$MACH.ref/interfaces\ \\\\
 213 .B \ \ \ \ \ \ \ $SRC/ELF-data.$MACH/interfaces
 214 lib/libadm.so.1: SUNW_1.1: added interface: circf(4)
 215 lib/libaio.so.1: SUNW_1.1: deleted interface: _aiocancel
 216 .fi
 217 .RE
 218 .sp
 219 .PP
 220 Note: the above comparison files were doctored in order to provide
 221 the example, they do not indicate any real changes that have
 222 occurred in the associated system libraries.
 223 .br
 224 .SH SEE ALSO
 225 .BR find_elf(1ONBLD),
 226 .BR interface_check(1ONBLD),
 227 .BR ld(1),
 228 .BR ldd(1),
 229 .BR elfdump(1),
 230 .BR pvs(1).