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_check.1onbld
+++ new/usr/src/tools/scripts/interface_check.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_check 1ONBLD "25 March 2010"
22 +.TH INTERFACE_CHECK 1ONBLD "Mar 25, 2010"
23 23 .SH NAME
24 24 interface_check \- check shared object interfaces
25 25 .SH SYNOPSIS
26 26 \fBinterface_check [-hIo] [-c vertype_module] [-E errfile] [-e exfile] [-f listfile] [-i intffile] [-w outdir] file | dir, ...\fP
27 -.LP
28 27 .SH DESCRIPTION
29 -.IX "OS-Net build tools" "interface_check" "" "\fBinterface_check\fP"
30 28 The
31 29 .I interface_check
32 30 command attempts to check a number of ELF versioning attributes
33 31 for consistency with common build rules and practices.
34 32 In addition, a complete breakdown of the file's version definitions can
35 33 be captured using the
36 34 .B -i
37 35 option, and the interface description file created can be used with
38 36 .I interface_cmp
39 37 to audit
40 38 the versioning evolution of a software product.
41 39 These interface description files reflect the association of the shared
42 40 object's global symbols with recorded version definitions.
|
↓ open down ↓ |
3 lines elided |
↑ open up ↑ |
43 41 .LP
44 42 .I interface_check
45 43 is typically called from \fBnightly(1ONBLD)\fP when the \fB-A\fP
46 44 option is in effect. In this case the shared objects under
47 45 the associated \fIproto\fP area (\fB$ROOT\fP) are examined.
48 46 .I interface_check
49 47 can also be run standalone against any set of dynamic objects.
50 48 .LP
51 49 .I interface_check
52 50 uses \fBelfdump(1)\fP and \fBpvs(1)\fP to
53 -check file naming standardization, and versioning consistency. These
51 +check file naming standardization, and versioning consistency. These
54 52 check are carried out for the following reasons:
55 53 .TP 4
56 54 \(bu
57 55 A shared object should exist with a versioned filename.
58 56 A versioned filename commonly takes the form of a \fI.so\fP suffix
59 57 followed by a version number. For example, \fI/usr/lib/libc.so.1\fP
60 58 is the shared object representation of version one of the standard C
61 59 library made available to the runtime environment.
62 60 A versioned filename allows for a change in the exported interface of
63 61 the shared object over a series of software releases. A shared object
64 62 that doesn't exist as a versioned filename is displayed as:
65 63 .sp
66 64 .RS 6
67 65 foo.so: does not have a versioned name
68 66 .RE
69 67 .TP
70 68 \(bu
71 69 Versions should be defined within a shared object both to clarify its
72 70 public or private use, and to explicitly define the interfaces that it
73 71 makes available. The reduction in object size, and relocation cost
74 72 created by reducing non-interface symbols to locals is an added bonus.
75 73 A non-versioned shared object is displayed as:
76 74 .sp
77 75 .RS 6
78 76 foo.so.1: no versions found
79 77 .RE
80 78 .TP
81 79 \(bu
82 80 Version definitions should follow a standard naming convention, i.e.,
83 81 \fBSUNW_\fIx.y\fP\fP, \fBSUNWprivate_\fIx.y\fP\fP, or \fIfilename\fP. The
84 82 latter version is a base version and is used to capture any reserved
85 83 interface symbols (i.e., \fI_end\fP, \fI_etext\fP, etc.). Any non-conforming
86 84 version names are displayed as:
87 85 .sp
88 86 .RS 6
89 87 foo.so.1: non-standard version name: \fIversion-name\fP
90 88 .RE
91 89 .sp
92 90 .RS 4
93 91 Note, that non-conforming base version names are often generated when
94 92 the file itself has an internal identification that differs from the
95 93 actual filename (see \fBld(1)\fP \fI-h\fP).
96 94 .RE
97 95 .TP
98 96 \(bu
99 97 A scoped object, one that has defined its external interfaces
100 98 and whose internal interfaces have been reduced to locals,
|
↓ open down ↓ |
37 lines elided |
↑ open up ↑ |
101 99 but has no version definitions assigned, does not inform users
102 100 of the commitment level of the interfaces it offers. Scoped
103 101 objects are displayed as:
104 102 .sp
105 103 .RS 6
106 104 foo.so.1: scoped object contains no versions
107 105 .LP
108 106 When used with the \fI-i\fP option
109 107 .I interface_check
110 108 produces a more detailed breakdown of a shared objects versioning.
111 -This interface description file provides for the release-to-release
109 +This interface description file provides for the release-to-release
112 110 auditing of interfaces,
113 111 and monitoring the evolution of the share objects interfaces.
114 112 .LP
115 113 These files provide a complete cross reference of version to interface
116 114 relationships and are the basis for
117 115 auditing a shared objects interfaces from release-to-release. Any
118 116 addition, deletion or regrouping of versioning information can be
119 117 detected by inspecting this database with
120 118 .I interface_cmp.
121 119 .sp
122 -.LP
123 120 .SH OPTIONS
124 121 .LP
125 122 The following options are supported:
126 123 .TP 4
127 124 .B \-c vertype_module
128 125 By default,
129 126 .I interface_check
130 127 is customized for the versioning conventions used by the Solaris
131 128 OSnet code base. This specialized information, which includes
132 129 the recognition of the SUNW_ prefix and other special names, is
133 130 contained in a perl module named onbld_elfmod_vertype.pm, which
134 131 is delivered with the SUNWonbld tools. This module is loaded by
135 132 .I interface_check
136 133 at runtime. The \fB-c\fP option can be used to supply
137 134 an alternative module, customized for a different code base, allowing
138 135 .I interface_check
139 136 to operate on code from other projects. The alternative module must
140 137 supply the same module and calling interfaces as the standard module.
141 138 .TP 4
142 139 .B \-E errfile
143 -Direct error messages for the analyzed objects to \fIerrfile\fP instead
140 +Direct error messages for the analyzed objects to \fIerrfile\fP instead
144 141 of stdout.
145 142 .TP 4
146 143 .B \-e exfile
147 144 An exception file is used to exclude objects from
148 145 the usual rules. See EXCEPTION FILE FORMAT.
149 146 .TP 4
150 147 .B \-f listfile
151 148 Normally,
152 149 .I interface_check
153 150 runs
154 151 .I find_elf
155 152 to locate the ELF objects to analyze. The \fB-f\fP option can be
156 153 used to instead provide a file containing the list of objects to
157 154 analyze, in the format produced by '\fBfind_elf -r\fP'.
158 155 .TP 4
159 156 .B \-h
160 -Prevent the generation of the CDDL license and Sun copyright header
157 +Prevent the generation of the CDDL license and Sun copyright header
161 158 normally produced at the start of output.
162 159 .TP 4
163 160 .B \-I
164 161 When used with the \fB-i\fP option, the interface definition produced shows
165 162 expanded symbol inheritance. Each version lists the symbols inherited
166 163 from sub-versions. This mode is primarily of interest for debugging,
167 164 as it matches the format produced by the \fB-t\fP option to
168 165 .I interface_cmp. See INTERFACE DESCRIPTION FILE FORMAT.
169 166 .TP 4
170 167 .B \-i intffile
171 168 Produce an output file containing a complete interface definition for
172 169 the objects analyzed. This file can be used with
173 170 .I interface_cmp
174 171 to audit versioning between gates, or prior to integration within
175 172 a single gate. See INTERFACE DESCRIPTION FILE FORMAT.
176 173 .TP 4
177 174 .B \-o
178 -Produce one-liner output, with each line of diagnostic output
175 +Produce one-liner output, with each line of diagnostic output
179 176 prefixed with the object pathname.
180 177 .TP
181 178 .B -w outdir
182 179 Interpret the paths of all input and output files relative to \fIoutdir\fP.
183 -.LP
184 180 .SH EXCEPTION FILE FORMAT
185 181 Exceptions to the rules enforced by
186 182 .I interface_check
187 183 are be specified using an exception file. The \fB-e\fP option is used to
188 184 specify an explicit exception file. Otherwise, if used in an activated
189 185 workspace, the default exception file is
190 186 $CODEMGR_WS/exception_list/interface_check
191 187 if that file exists. If not used in an activated workspace, or if
192 188 $CODEMGR_WS/exception_list/interface_check does not exist,
193 189 .I interface_check
194 190 will use
195 191 .I /opt/onbld/etc/exception_list/interface_check
196 192 as a fallback default exception file.
197 -.p
193 +.P
198 194 To run
199 195 .I interface_check
200 196 without applying exceptions, specify \fB-e\fP with a value of /dev/null.
201 197 .P
202 198 A '#' character at the beginning of a line, or at any point in
203 -a line when preceded by whitespace, introduces a comment. Empty lines,
199 +a line when preceded by whitespace, introduces a comment. Empty lines,
204 200 and lines containing only comments, are ignored by
205 201 .I interface_check.
206 202 Exceptions are specified as space separated keyword, and \fBperl(1)\fP
207 203 regular expression:
208 204 .sp
209 205 .in +4
210 206 .nf
211 207 keyword perl-regex
212 208 .fi
213 209 .in -4
214 210 .sp
215 211 Since whitespace is used as a separator, the regular
216 212 expression cannot itself contain whitespace. Use of the \\s character
217 213 class to represent whitespace within the regular expression is recommended.
218 214 Before the perl regular expression is used, constructs of the form
219 215 MACH(dir) are expanded into a regular expression that matches the directory
220 216 given, as well as any 64-bit architecture subdirectory that
221 217 might be present (i.e. amd64, sparcv9). For instance, MACH(lib) will
222 218 match any of the following:
223 219 .sp
224 220 .in +4
225 221 .nf
226 222 lib
|
↓ open down ↓ |
13 lines elided |
↑ open up ↑ |
227 223 lib/amd64
228 224 lib/sparcv9
229 225 .fi
230 226 .in -4
231 227 .sp
232 228 The exceptions understood by
233 229 .I interface_check
234 230 are:
235 231 .sp
236 232 .ne 2
237 -.mk
238 233 .na
239 234 \fBNONSTD_VERNAME\fR
240 235 .ad
241 236 .RS 17n
242 -.rt
243 237 .sp
244 238 Objects that are allowed to deviate from our standard version names.
245 239 .RE
246 240
247 241 .sp
248 242 .ne 2
249 -.mk
250 243 .na
251 244 \fBNOVERDEF\fR
252 245 .ad
253 246 .RS 17n
254 -.rt
255 247 Objects that are not expected to contain versioning information.
256 248 Note that PLUGIN objects are automatically exempt from this,
257 249 so these directives are generally applied to non-plugin objects
258 250 .RE
259 251
260 252 .sp
261 253 .ne 2
262 -.mk
263 254 .na
264 255 \fBPLUGIN\fR
265 256 .ad
266 257 .RS 17n
267 -.rt
268 258 Sharable objects underneath these parts of the tree are taken to be plugins.
269 259 Plugins are not required to have versioned file names, and are not required
270 260 to be internally versioned.
271 261 .RE
272 -.LP
273 262 .SH INTERFACE DESCRIPTION FILE FORMAT
274 263 When the \fB-i\fP option is used
275 264 .I interface_check
276 265 produces an \fIInterface Description File\fP that captures a description of
277 -the interfaces provided by each ELF object processed.
266 +the interfaces provided by each ELF object processed.
278 267 .P
279 268 Unless the \fB-h\fP option is used,
280 269 .I interface_check
281 270 produces a header comment at the start of this file, containing a CDDL
282 271 block and a Sun copyright notice. The header uses '#' as a comment character
283 272 for the lines containing text, and also includes empty lines.
284 273 .P
285 274 Following the header comment,
286 275 .I interface_check
287 276 produces a description of the interfaces provided by each object. The
288 277 description of each object starts with an OBJECT directive, and follows the
289 278 form shown below, using /lib/amd64/libadm.so.1 as an example:
290 279 .sp
291 280 .in +4
292 281 .nf
293 -.CR
294 282 OBJECT lib/amd64/libadm.so.1
295 283 CLASS ELFCLASS64
296 284 TYPE ET_DYN
297 285 ALIAS lib/64/libadm.so
298 286 ALIAS lib/64/libadm.so.1
299 287 ALIAS lib/amd64/libadm.so
300 288 ALIAS usr/lib/64/libadm.so
301 289 ALIAS usr/lib/64/libadm.so.1
302 290 ALIAS usr/lib/amd64/libadm.so
303 291 ALIAS usr/lib/amd64/libadm.so.1
304 292 TOP_VERSION SUNW_1.2 {SUNW_1.1}
305 293 SYMBOL read_extvtoc
306 294 SYMBOL write_extvtoc
307 295 VERSION SUNW_1.1 {SUNW_0.7}
308 296 VERSION SUNW_0.7
309 297 SYMBOL pkgdir
310 298 SYMBOL read_vtoc
311 299 SYMBOL write_vtoc
312 300 .fi
313 301 .in -4
314 302 .sp
315 303 The description for every object starts with OBJECT, CLASS, and TYPE
316 304 directives. Following that come ALIAS lines for every alternative name
317 305 by which this object is known. Every version exported by the object
318 306 is designated by a VERSION or TOP_VERSION directive. A TOP_VERSION is
319 307 a version at the top of the version inheritance chain, and VERSION
320 308 is used for versions lower in the chain. Inherited versions are shown
321 309 within {} brackets following the version name. Following each version directive
322 310 are SYMBOL directives, each describing a symbol defined by
|
↓ open down ↓ |
19 lines elided |
↑ open up ↑ |
323 311 that version.
324 312 .P
325 313 When the \fB-I\fP option is used, version inheritance is expanded,
326 314 such that each version includes the symbols inherited from sub-versions.
327 315 In this mode, the SYMBOL directive is replaced with NEW for symbols
328 316 defined in the version, and INHERIT for those that are inherited. Using
329 317 \fB-I\fP for the above example produces the following output:
330 318 .sp
331 319 .in +4
332 320 .nf
333 -.CR
334 321 OBJECT lib/amd64/libadm.so.1
335 322 CLASS ELFCLASS64
336 323 TYPE ET_DYN
337 324 ALIAS lib/64/libadm.so
338 325 ALIAS lib/64/libadm.so.1
339 326 ALIAS lib/amd64/libadm.so
340 327 ALIAS usr/lib/64/libadm.so
341 328 ALIAS usr/lib/64/libadm.so.1
342 329 ALIAS usr/lib/amd64/libadm.so
343 330 ALIAS usr/lib/amd64/libadm.so.1
344 331 TOP_VERSION SUNW_1.2 {SUNW_1.1}
345 332 INHERIT pkgdir
346 333 NEW read_extvtoc
347 334 INHERIT read_vtoc
348 335 NEW write_extvtoc
349 336 INHERIT write_vtoc
350 337 VERSION SUNW_1.1 {SUNW_0.7}
351 338 INHERIT pkgdir
352 339 INHERIT read_vtoc
353 340 INHERIT write_vtoc
354 341 VERSION SUNW_0.7
|
↓ open down ↓ |
11 lines elided |
↑ open up ↑ |
355 342 NEW pkgdir
356 343 NEW read_vtoc
357 344 NEW write_vtoc
358 345 .fi
359 346 .in -4
360 347 .sp
361 348 The \fB-I\fP option is primary used for debugging
362 349 .I interface_check
363 350 and
364 351 .I interface_cmp.
365 -.LP
366 352 .SH EXAMPLES
367 353 The following example uses
368 354 .I interface_check
369 355 to generate an interface database for a workspace:
370 356 .PP
371 357 .RS
372 358 .nf
373 359 % mkdir $SRC/ELF-data.$MACH
374 360 % interface_check -w $SRC/ELF-data.$MACH -E interface.err \
375 361 -i interface $ROOT
376 362 % ls -1R $SRC/ELF
377 363 interface
378 364 interface.err
379 365 .br
380 366 .SH FILES
381 367 .LP
|
↓ open down ↓ |
6 lines elided |
↑ open up ↑ |
382 368 .RS 5
383 369 $CODEMGR_WS/exception_list/interface_check
384 370 /opt/onbld/etc/exception_list/interface_check
385 371 .SH SEE ALSO
386 372 .BR find_elf(1ONBLD),
387 373 .BR interface_cmp(1ONBLD),
388 374 .BR ld(1),
389 375 .BR ldd(1),
390 376 .BR elfdump(1),
391 377 .BR pvs(1).
392 -.LP
393 -.TZ LLM
378 +
379 +
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX