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_check 1ONBLD "25 March 2010"
  23 .SH NAME
  24 interface_check \- check shared object interfaces
  25 .SH SYNOPSIS
  26 \fBinterface_check [-hIo] [-c vertype_module] [-E errfile] [-e exfile] [-f listfile] [-i intffile] [-w outdir] file | dir, ...\fP
  27 .LP
  28 .SH DESCRIPTION
  29 .IX "OS-Net build tools" "interface_check" "" "\fBinterface_check\fP"
  30 The
  31 .I interface_check
  32 command attempts to check a number of ELF versioning attributes
  33 for consistency with common build rules and practices.
  34 In addition, a complete breakdown of the file's version definitions can
  35 be captured using the
  36 .B -i
  37 option, and the interface description file created can be used with
  38 .I interface_cmp
  39 to audit
  40 the versioning evolution of a software product.
  41 These interface description files reflect the association of the shared
  42 object's global symbols with recorded version definitions.
  43 .LP
  44 .I interface_check
  45 is typically called from \fBnightly(1ONBLD)\fP when the \fB-A\fP
  46 option is in effect. In this case the shared objects under
  47 the associated \fIproto\fP area (\fB$ROOT\fP) are examined.
  48 .I interface_check
  49 can also be run standalone against any set of dynamic objects.
  50 .LP
  51 .I interface_check
  52 uses \fBelfdump(1)\fP and \fBpvs(1)\fP to
  53 check file naming standardization, and versioning consistency. These 
  54 check are carried out for the following reasons:
  55 .TP 4
  56 \(bu
  57 A shared object should exist with a versioned filename.
  58 A versioned filename commonly takes the form of a \fI.so\fP suffix
  59 followed by a version number. For example, \fI/usr/lib/libc.so.1\fP
  60 is the shared object representation of version one of the standard C
  61 library made available to the runtime environment.
  62 A versioned filename allows for a change in the exported interface of
  63 the shared object over a series of software releases.  A shared object
  64 that doesn't exist as a versioned filename is displayed as:
  65 .sp
  66 .RS 6
  67 foo.so: does not have a versioned name
  68 .RE
  69 .TP
  70 \(bu
  71 Versions should be defined within a shared object both to clarify its
  72 public or private use, and to explicitly define the interfaces that it
  73 makes available.  The reduction in object size, and relocation cost
  74 created by reducing non-interface symbols to locals is an added bonus.
  75 A non-versioned shared object is displayed as:
  76 .sp
  77 .RS 6
  78 foo.so.1: no versions found
  79 .RE
  80 .TP
  81 \(bu
  82 Version definitions should follow a standard naming convention, i.e.,
  83 \fBSUNW_\fIx.y\fP\fP, \fBSUNWprivate_\fIx.y\fP\fP, or \fIfilename\fP.  The
  84 latter version is a base version and is used to capture any reserved
  85 interface symbols (i.e., \fI_end\fP, \fI_etext\fP, etc.).  Any non-conforming
  86 version names are displayed as:
  87 .sp
  88 .RS 6
  89 foo.so.1: non-standard version name: \fIversion-name\fP
  90 .RE
  91 .sp
  92 .RS 4
  93 Note, that non-conforming base version names are often generated when
  94 the file itself has an internal identification that differs from the
  95 actual filename (see \fBld(1)\fP \fI-h\fP).
  96 .RE
  97 .TP
  98 \(bu
  99 A scoped object, one that has defined its external interfaces
 100 and whose internal interfaces have been reduced to locals,
 101 but has no version definitions assigned, does not inform users
 102 of the commitment level of the interfaces it offers. Scoped
 103 objects are displayed as:
 104 .sp
 105 .RS 6
 106 foo.so.1: scoped object contains no versions
 107 .LP
 108 When used with the \fI-i\fP option
 109 .I interface_check
 110 produces a more detailed breakdown of a shared objects versioning.
 111 This interface description file provides for the release-to-release 
 112 auditing of interfaces,
 113 and monitoring the evolution of the share objects interfaces.
 114 .LP
 115 These files provide a complete cross reference of version to interface
 116 relationships and are the basis for
 117 auditing a shared objects interfaces from release-to-release.  Any
 118 addition, deletion or regrouping of versioning information can be
 119 detected by inspecting this database with
 120 .I interface_cmp.
 121 .sp
 122 .LP
 123 .SH OPTIONS
 124 .LP
 125 The following options are supported:
 126 .TP 4
 127 .B \-c vertype_module
 128 By default,
 129 .I interface_check
 130 is customized for the versioning conventions used by the Solaris
 131 OSnet code base. This specialized information, which includes
 132 the recognition of the SUNW_ prefix and other special names, is
 133 contained in a perl module named onbld_elfmod_vertype.pm, which
 134 is delivered with the SUNWonbld tools. This module is loaded by
 135 .I interface_check
 136 at runtime. The \fB-c\fP option can be used to supply
 137 an alternative module, customized for a different code base, allowing
 138 .I interface_check
 139 to operate on code from other projects. The alternative module must
 140 supply the same module and calling interfaces as the standard module.
 141 .TP 4
 142 .B \-E errfile
 143 Direct error messages for the analyzed objects to \fIerrfile\fP instead 
 144 of stdout.
 145 .TP 4
 146 .B \-e exfile
 147 An exception file is used to exclude objects from
 148 the usual rules. See EXCEPTION FILE FORMAT.
 149 .TP 4
 150 .B \-f listfile
 151 Normally,
 152 .I interface_check
 153 runs
 154 .I find_elf
 155 to locate the ELF objects to analyze. The \fB-f\fP option can be
 156 used to instead provide a file containing the list of objects to
 157 analyze, in the format produced by '\fBfind_elf -r\fP'.
 158 .TP 4
 159 .B \-h
 160 Prevent the generation of the CDDL license and Sun copyright header 
 161 normally produced at the start of output.
 162 .TP 4
 163 .B \-I
 164 When used with the \fB-i\fP option, the interface definition produced shows
 165 expanded symbol inheritance. Each version lists the symbols inherited
 166 from sub-versions. This mode is primarily of interest for debugging,
 167 as it matches the format produced by the \fB-t\fP option to
 168 .I interface_cmp. See INTERFACE DESCRIPTION FILE FORMAT.
 169 .TP 4
 170 .B \-i intffile
 171 Produce an output file containing a complete interface definition for
 172 the objects analyzed. This file can be used with
 173 .I interface_cmp
 174 to audit versioning between gates, or prior to integration within
 175 a single gate. See INTERFACE DESCRIPTION FILE FORMAT.
 176 .TP 4
 177 .B \-o
 178 Produce one-liner output, with each line of diagnostic output 
 179 prefixed with the object pathname.
 180 .TP
 181 .B -w outdir
 182 Interpret the paths of all input and output files relative to \fIoutdir\fP.
 183 .LP
 184 .SH EXCEPTION FILE FORMAT
 185 Exceptions to the rules enforced by
 186 .I interface_check
 187 are be specified using an exception file. The \fB-e\fP option is used to
 188 specify an explicit exception file. Otherwise, if used in an activated
 189 workspace, the default exception file is
 190 $CODEMGR_WS/exception_list/interface_check
 191 if that file exists. If not used in an activated workspace, or if
 192 $CODEMGR_WS/exception_list/interface_check does not exist,
 193 .I interface_check
 194 will use
 195 .I /opt/onbld/etc/exception_list/interface_check
 196 as a fallback default exception file.
 197 .p
 198 To run
 199 .I interface_check
 200 without applying exceptions, specify \fB-e\fP with a value of /dev/null.
 201 .P
 202 A '#' character at the beginning of a line, or at any point in
 203 a line when preceded by whitespace, introduces a comment. Empty lines, 
 204 and lines containing only comments, are ignored by
 205 .I interface_check.
 206 Exceptions are specified as space separated keyword, and \fBperl(1)\fP
 207 regular expression:
 208 .sp
 209 .in +4
 210 .nf
 211 keyword  perl-regex
 212 .fi
 213 .in -4
 214 .sp
 215 Since whitespace is used as a separator, the regular
 216 expression cannot itself contain whitespace. Use of the \\s character
 217 class to represent whitespace within the regular expression is recommended.
 218 Before the perl regular expression is used, constructs of the form
 219 MACH(dir) are expanded into a regular expression that matches the directory
 220 given, as well as any 64-bit architecture subdirectory that
 221 might be present (i.e. amd64, sparcv9). For instance, MACH(lib) will
 222 match any of the following:
 223 .sp
 224 .in +4
 225 .nf
 226 lib
 227 lib/amd64
 228 lib/sparcv9
 229 .fi
 230 .in -4
 231 .sp
 232 The exceptions understood by
 233 .I interface_check
 234 are:
 235 .sp
 236 .ne 2
 237 .mk
 238 .na
 239 \fBNONSTD_VERNAME\fR
 240 .ad
 241 .RS 17n
 242 .rt
 243 .sp
 244 Objects that are allowed to deviate from our standard version names.
 245 .RE
 246 
 247 .sp
 248 .ne 2
 249 .mk
 250 .na
 251 \fBNOVERDEF\fR
 252 .ad
 253 .RS 17n
 254 .rt
 255 Objects that are not expected to contain versioning information.
 256 Note that PLUGIN objects are automatically exempt from this,
 257 so these directives are generally applied to non-plugin objects
 258 .RE
 259 
 260 .sp
 261 .ne 2
 262 .mk
 263 .na
 264 \fBPLUGIN\fR
 265 .ad
 266 .RS 17n
 267 .rt
 268 Sharable objects underneath these parts of the tree are taken to be plugins.
 269 Plugins are not required to have versioned file names, and are not required
 270 to be internally versioned.
 271 .RE
 272 .LP
 273 .SH INTERFACE DESCRIPTION FILE FORMAT
 274 When the \fB-i\fP option is used
 275 .I interface_check
 276 produces an \fIInterface Description File\fP that captures a description of
 277 the interfaces provided by each ELF object processed. 
 278 .P
 279 Unless the \fB-h\fP option is used,
 280 .I interface_check
 281 produces a header comment at the start of this file, containing a CDDL
 282 block and a Sun copyright notice. The header uses '#' as a comment character
 283 for the lines containing text, and also includes empty lines.
 284 .P
 285 Following the header comment,
 286 .I interface_check
 287 produces a description of the interfaces provided by each object. The
 288 description of each object starts with an OBJECT directive, and follows the
 289 form shown below, using /lib/amd64/libadm.so.1 as an example:
 290 .sp
 291 .in +4
 292 .nf
 293 .CR
 294 OBJECT  lib/amd64/libadm.so.1
 295 CLASS   ELFCLASS64
 296 TYPE    ET_DYN
 297 ALIAS   lib/64/libadm.so
 298 ALIAS   lib/64/libadm.so.1
 299 ALIAS   lib/amd64/libadm.so
 300 ALIAS   usr/lib/64/libadm.so
 301 ALIAS   usr/lib/64/libadm.so.1
 302 ALIAS   usr/lib/amd64/libadm.so
 303 ALIAS   usr/lib/amd64/libadm.so.1
 304 TOP_VERSION     SUNW_1.2        {SUNW_1.1}
 305         SYMBOL  read_extvtoc
 306         SYMBOL  write_extvtoc
 307 VERSION SUNW_1.1        {SUNW_0.7}
 308 VERSION SUNW_0.7
 309         SYMBOL  pkgdir
 310         SYMBOL  read_vtoc
 311         SYMBOL  write_vtoc
 312 .fi
 313 .in -4
 314 .sp
 315 The description for every object starts with OBJECT, CLASS, and TYPE
 316 directives. Following that come ALIAS lines for every alternative name
 317 by which this object is known. Every version exported by the object
 318 is designated by a VERSION or TOP_VERSION directive. A TOP_VERSION is
 319 a version at the top of the version inheritance chain, and VERSION
 320 is used for versions lower in the chain. Inherited versions are shown
 321 within {} brackets following the version name. Following each version directive
 322 are SYMBOL directives, each describing a symbol defined by
 323 that version.
 324 .P
 325 When the \fB-I\fP option is used, version inheritance is expanded,
 326 such that each version includes the symbols inherited from sub-versions.
 327 In this mode, the SYMBOL directive is replaced with NEW for symbols
 328 defined in the version, and INHERIT for those that are inherited. Using
 329 \fB-I\fP for the above example produces the following output:
 330 .sp
 331 .in +4
 332 .nf
 333 .CR
 334 OBJECT  lib/amd64/libadm.so.1
 335 CLASS   ELFCLASS64
 336 TYPE    ET_DYN
 337 ALIAS   lib/64/libadm.so
 338 ALIAS   lib/64/libadm.so.1
 339 ALIAS   lib/amd64/libadm.so
 340 ALIAS   usr/lib/64/libadm.so
 341 ALIAS   usr/lib/64/libadm.so.1
 342 ALIAS   usr/lib/amd64/libadm.so
 343 ALIAS   usr/lib/amd64/libadm.so.1
 344 TOP_VERSION     SUNW_1.2        {SUNW_1.1}
 345         INHERIT pkgdir
 346         NEW     read_extvtoc
 347         INHERIT read_vtoc
 348         NEW     write_extvtoc
 349         INHERIT write_vtoc
 350 VERSION SUNW_1.1        {SUNW_0.7}
 351         INHERIT pkgdir
 352         INHERIT read_vtoc
 353         INHERIT write_vtoc
 354 VERSION SUNW_0.7
 355         NEW     pkgdir
 356         NEW     read_vtoc
 357         NEW     write_vtoc
 358 .fi
 359 .in -4
 360 .sp
 361 The \fB-I\fP option is primary used for debugging
 362 .I interface_check
 363 and
 364 .I interface_cmp.
 365 .LP
 366 .SH EXAMPLES
 367 The following example uses
 368 .I interface_check
 369 to generate an interface database for a workspace:
 370 .PP
 371 .RS
 372 .nf
 373 % mkdir $SRC/ELF-data.$MACH
 374 % interface_check -w $SRC/ELF-data.$MACH -E interface.err \ 
 375         -i interface $ROOT
 376 % ls -1R $SRC/ELF
 377 interface
 378 interface.err
 379 .br
 380 .SH FILES
 381 .LP
 382 .RS 5
 383 $CODEMGR_WS/exception_list/interface_check
 384 /opt/onbld/etc/exception_list/interface_check
 385 .SH SEE ALSO
 386 .BR find_elf(1ONBLD),
 387 .BR interface_cmp(1ONBLD),
 388 .BR ld(1),
 389 .BR ldd(1),
 390 .BR elfdump(1),
 391 .BR pvs(1).
 392 .LP
 393 .TZ LLM