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