1 interface_cmp(1ONBLD) illumos Build Tools interface_cmp(1ONBLD) 2 3 4 5 NAME 6 interface_cmp - compare shared object interface descriptions 7 8 SYNOPSIS 9 interface_cmp [-dot] [-e exfile] old new 10 11 DESCRIPTION 12 The interface_cmp command compares the interface definition files for 13 two workspaces and reports versioning inconsistencies. Interface 14 definition files are created by interface_check. 15 16 interface_cmp is typically called from nightly(1ONBLD) when the -A 17 option is in effect following the creation of a new database by 18 interface_check. To insure symbolic interface consistency between 19 successive software releases, existing version definitions and their 20 symbol association should remain intact. Any discrepancies between the 21 two interface definitions are flagged as errors. 22 23 Note that version definition inheritance has the effect of causing a 24 symbol to be viewed as existing in multiple definitions. This insures 25 that both version definitions and their inheritance relationship are 26 processed as part of the comparison. 27 28 OPTIONS 29 The following options are supported: 30 31 -c vertype_module 32 By default, interface_cmp is customized for the versioning 33 conventions used by the Solaris OSnet code base. This specialized 34 information, which includes the recognition of the SUNW_ prefix and 35 other special names, is contained in a perl module named 36 onbld_elfmod_vertype.pm, which is delivered with the SUNWonbld 37 tools. This module is loaded by interface_cmp at runtime. The -c 38 option can be used to supply an alternative module, customized for 39 a different code base, allowing interface_cmp to operate on code 40 from other projects. The alternative module must supply the same 41 module and calling interfaces as the standard module. 42 43 -d Asserts that the new interface is a direct descendant of old. If 44 so, the following additional checks are enabled: 45 46 o The top version of an inheritance chain must not increase by 47 more than one. 48 49 o The new interface must not add new empty versions. Pre-existing 50 empty versions represent public interfaces that cannot be 51 changed, but new ones should be removed before the product 52 ships. 53 54 55 -e exfile 56 An exception file is used to exclude objects from the usual rules. 57 See EXCEPTION FILE FORMAT. 58 59 -o Produce one-liner output, with each line of diagnostic output 60 prefixed with the object pathname. 61 62 -t If the -t option is present, only one argument is allowed. The 63 interface description file is parsed, and then regenerated on 64 stdout in the same format used by the interface_check -I option. 65 The -I output from interface_check and the output from 66 interface_cmp -t should be identical, excluding header comments. 67 This is a debugging feature, and not intended for general use. 68 69 EXCEPTION FILE FORMAT 70 Exceptions to the rules enforced by interface_cmp are specified using 71 an exception file. The -e option is used to specify an explicit 72 exception file. Otherwise, if used in an activated workspace, the 73 default exception file is $CODEMGR_WS/exception_list/interface_cmp if 74 that file exists. If not used in an activated workspace, or if 75 $CODEMGR_WS/exception_list/interface_cmp does not exist, interface_cmp 76 will use /opt/onbld/etc/exception_list/interface_cmp as a fallback 77 default exception file. To run interface_cmp without applying 78 exceptions, specify -e with a value of /dev/null. 79 80 A '#' character at the beginning of a line, or at any point in a line 81 when preceded by whitespace, introduces a comment. Empty lines, and 82 lines containing only comments, are ignored by interface_cmp. 83 Exceptions are specified as space separated keyword, and perl(1) 84 regular expressions. The number of regular expressions depends on the 85 particular exception in questions: 86 87 keyword perl-regex... 88 89 Since whitespace is used as a separator, the regular expression cannot 90 itself contain whitespace. Use of the \s character class to represent 91 whitespace within the regular expression is recommended. Before the 92 perl regular expression is used, constructs of the form MACH(dir) are 93 expanded into a regular expression that matches the directory given, as 94 well as any 64-bit architecture subdirectory that might be present 95 (i.e. amd64, sparcv9). For instance, MACH(lib) will match any of the 96 following: 97 98 lib 99 lib/amd64 100 lib/sparcv9 101 102 The exceptions understood by interface_cmp are: 103 104 ADDSYM sym_re version_re object_re 105 106 The interfaces in a given version are not supposed to 107 change. interface_cmp will normally issue an error if 108 a new interface is added to a previously released 109 version. ADDSYM is used to override this requirement. 110 If the added symbol, version, and object match the 111 regular expressions specified by ADDSYM, the added 112 symbol is ignored. 113 114 115 DELDYM sym_re version_re object_re 116 117 Once released to the public, interfaces are required 118 to remain available in subsequent releases. DELSYM is 119 used to override this requirement, as can occur when 120 interfaces are EOL'd. Such an action generally 121 requires a PSARC case. If the deleted symbol, version, 122 and object match the regular expressions specified by 123 DELSYM, the deleted symbol is ignored. 124 125 126 EMPTY_TOPVERSION version_re object_re 127 128 interface_cmp normally issues an error if the old 129 object has an empty top version that is non-empty in 130 the new object. Such a situation is normally an error, 131 but may legitimately occur as part of a fix to another 132 versioning error. If the version, and object match 133 the regular expressions specified by EMPTY_TOPVERSION, 134 the error is suppressed. 135 136 137 EXAMPLES 138 The following example uses interface_cmp to compare this releases 139 interface definition with a previous builds results: 140 141 % interface_cmp -d -o $SRC/ELF-data.$MACH.ref/interfaces \ 142 $SRC/ELF-data.$MACH/interfaces 143 lib/libadm.so.1: SUNW_1.1: added interface: circf(4) 144 lib/libaio.so.1: SUNW_1.1: deleted interface: _aiocancel 145 146 147 Note: the above comparison files were doctored in order to provide the 148 example, they do not indicate any real changes that have occurred in 149 the associated system libraries. 150 151 SEE ALSO 152 find_elf(1ONBLD), interface_check(1ONBLD), ld(1), ldd(1), elfdump(1), 153 pvs(1). 154 155 156 157 25 March 2010 interface_cmp(1ONBLD)