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