Print this page
6282 ONBLD man pages not pbchk clean
Reviewed by: Yuri Pankov <yuri.pankov@nexenta.com>
Reviewed by: Josef Sipek <jeffpc@josefsipek.net>
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/tools/scripts/interface_cmp.1onbld.man.txt
+++ new/usr/src/tools/scripts/interface_cmp.1onbld.man.txt
1 -interface_cmp(1ONBLD) illumos Build Tools interface_cmp(1ONBLD)
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 16 interface_cmp is typically called from nightly(1ONBLD) when the -A
17 17 option is in effect following the creation of a new database by
18 18 interface_check. To insure symbolic interface consistency between
19 19 successive software releases, existing version definitions and their
20 20 symbol association should remain intact. Any discrepancies between the
21 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.
|
↓ open down ↓ |
55 lines elided |
↑ open up ↑ |
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 - default exception file. To run interface_cmp without applying
78 - exceptions, specify -e with a value of /dev/null.
77 + default exception file.
79 78
79 + To run interface_cmp without applying exceptions, specify -e with a
80 + value of /dev/null.
81 +
80 82 A '#' character at the beginning of a line, or at any point in a line
81 83 when preceded by whitespace, introduces a comment. Empty lines, and
82 84 lines containing only comments, are ignored by interface_cmp.
83 85 Exceptions are specified as space separated keyword, and perl(1)
84 86 regular expressions. The number of regular expressions depends on the
85 87 particular exception in questions:
86 88
87 89 keyword perl-regex...
88 90
89 91 Since whitespace is used as a separator, the regular expression cannot
90 92 itself contain whitespace. Use of the \s character class to represent
91 93 whitespace within the regular expression is recommended. Before the
92 94 perl regular expression is used, constructs of the form MACH(dir) are
93 95 expanded into a regular expression that matches the directory given, as
94 96 well as any 64-bit architecture subdirectory that might be present
95 97 (i.e. amd64, sparcv9). For instance, MACH(lib) will match any of the
96 98 following:
97 99
98 100 lib
99 101 lib/amd64
100 102 lib/sparcv9
101 103
102 104 The exceptions understood by interface_cmp are:
103 105
104 106 ADDSYM sym_re version_re object_re
105 107
106 108 The interfaces in a given version are not supposed to
107 109 change. interface_cmp will normally issue an error if
108 110 a new interface is added to a previously released
109 111 version. ADDSYM is used to override this requirement.
110 112 If the added symbol, version, and object match the
111 113 regular expressions specified by ADDSYM, the added
112 114 symbol is ignored.
113 115
114 116
115 117 DELDYM sym_re version_re object_re
116 118
117 119 Once released to the public, interfaces are required
118 120 to remain available in subsequent releases. DELSYM is
119 121 used to override this requirement, as can occur when
120 122 interfaces are EOL'd. Such an action generally
121 123 requires a PSARC case. If the deleted symbol, version,
122 124 and object match the regular expressions specified by
123 125 DELSYM, the deleted symbol is ignored.
124 126
125 127
126 128 EMPTY_TOPVERSION version_re object_re
127 129
128 130 interface_cmp normally issues an error if the old
129 131 object has an empty top version that is non-empty in
130 132 the new object. Such a situation is normally an error,
131 133 but may legitimately occur as part of a fix to another
132 134 versioning error. If the version, and object match
133 135 the regular expressions specified by EMPTY_TOPVERSION,
134 136 the error is suppressed.
135 137
136 138
137 139 EXAMPLES
138 140 The following example uses interface_cmp to compare this releases
139 141 interface definition with a previous builds results:
140 142
141 143 % interface_cmp -d -o $SRC/ELF-data.$MACH.ref/interfaces \
142 144 $SRC/ELF-data.$MACH/interfaces
143 145 lib/libadm.so.1: SUNW_1.1: added interface: circf(4)
144 146 lib/libaio.so.1: SUNW_1.1: deleted interface: _aiocancel
145 147
146 148
|
↓ open down ↓ |
57 lines elided |
↑ open up ↑ |
147 149 Note: the above comparison files were doctored in order to provide the
148 150 example, they do not indicate any real changes that have occurred in
149 151 the associated system libraries.
150 152
151 153 SEE ALSO
152 154 find_elf(1ONBLD), interface_check(1ONBLD), ld(1), ldd(1), elfdump(1),
153 155 pvs(1).
154 156
155 157
156 158
157 - 25 March 2010 interface_cmp(1ONBLD)
159 + March 25, 2010 INTERFACE_CMP(1ONBLD)
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX