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