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