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