2 .\"
3 .\" CDDL HEADER START
4 .\"
5 .\" The contents of this file are subject to the terms of the
6 .\" Common Development and Distribution License (the "License").
7 .\" You may not use this file except in compliance with the License.
8 .\"
9 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
10 .\" or http://www.opensolaris.org/os/licensing.
11 .\" See the License for the specific language governing permissions
12 .\" and limitations under the License.
13 .\"
14 .\" When distributing Covered Code, include this CDDL HEADER in each
15 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
16 .\" If applicable, add the following below this CDDL HEADER, with the
17 .\" fields enclosed by brackets "[]" replaced with your own identifying
18 .\" information: Portions Copyright [yyyy] [name of copyright owner]
19 .\"
20 .\" CDDL HEADER END
21 .\"
22 .TH interface_check 1ONBLD "25 March 2010"
23 .SH NAME
24 interface_check \- check shared object interfaces
25 .SH SYNOPSIS
26 \fBinterface_check [-hIo] [-c vertype_module] [-E errfile] [-e exfile] [-f listfile] [-i intffile] [-w outdir] file | dir, ...\fP
27 .LP
28 .SH DESCRIPTION
29 .IX "OS-Net build tools" "interface_check" "" "\fBinterface_check\fP"
30 The
31 .I interface_check
32 command attempts to check a number of ELF versioning attributes
33 for consistency with common build rules and practices.
34 In addition, a complete breakdown of the file's version definitions can
35 be captured using the
36 .B -i
37 option, and the interface description file created can be used with
38 .I interface_cmp
39 to audit
40 the versioning evolution of a software product.
41 These interface description files reflect the association of the shared
42 object's global symbols with recorded version definitions.
43 .LP
44 .I interface_check
45 is typically called from \fBnightly(1ONBLD)\fP when the \fB-A\fP
46 option is in effect. In this case the shared objects under
47 the associated \fIproto\fP area (\fB$ROOT\fP) are examined.
48 .I interface_check
49 can also be run standalone against any set of dynamic objects.
102 of the commitment level of the interfaces it offers. Scoped
103 objects are displayed as:
104 .sp
105 .RS 6
106 foo.so.1: scoped object contains no versions
107 .LP
108 When used with the \fI-i\fP option
109 .I interface_check
110 produces a more detailed breakdown of a shared objects versioning.
111 This interface description file provides for the release-to-release
112 auditing of interfaces,
113 and monitoring the evolution of the share objects interfaces.
114 .LP
115 These files provide a complete cross reference of version to interface
116 relationships and are the basis for
117 auditing a shared objects interfaces from release-to-release. Any
118 addition, deletion or regrouping of versioning information can be
119 detected by inspecting this database with
120 .I interface_cmp.
121 .sp
122 .LP
123 .SH OPTIONS
124 .LP
125 The following options are supported:
126 .TP 4
127 .B \-c vertype_module
128 By default,
129 .I interface_check
130 is customized for the versioning conventions used by the Solaris
131 OSnet code base. This specialized information, which includes
132 the recognition of the SUNW_ prefix and other special names, is
133 contained in a perl module named onbld_elfmod_vertype.pm, which
134 is delivered with the SUNWonbld tools. This module is loaded by
135 .I interface_check
136 at runtime. The \fB-c\fP option can be used to supply
137 an alternative module, customized for a different code base, allowing
138 .I interface_check
139 to operate on code from other projects. The alternative module must
140 supply the same module and calling interfaces as the standard module.
141 .TP 4
142 .B \-E errfile
163 .B \-I
164 When used with the \fB-i\fP option, the interface definition produced shows
165 expanded symbol inheritance. Each version lists the symbols inherited
166 from sub-versions. This mode is primarily of interest for debugging,
167 as it matches the format produced by the \fB-t\fP option to
168 .I interface_cmp. See INTERFACE DESCRIPTION FILE FORMAT.
169 .TP 4
170 .B \-i intffile
171 Produce an output file containing a complete interface definition for
172 the objects analyzed. This file can be used with
173 .I interface_cmp
174 to audit versioning between gates, or prior to integration within
175 a single gate. See INTERFACE DESCRIPTION FILE FORMAT.
176 .TP 4
177 .B \-o
178 Produce one-liner output, with each line of diagnostic output
179 prefixed with the object pathname.
180 .TP
181 .B -w outdir
182 Interpret the paths of all input and output files relative to \fIoutdir\fP.
183 .LP
184 .SH EXCEPTION FILE FORMAT
185 Exceptions to the rules enforced by
186 .I interface_check
187 are be specified using an exception file. The \fB-e\fP option is used to
188 specify an explicit exception file. Otherwise, if used in an activated
189 workspace, the default exception file is
190 $CODEMGR_WS/exception_list/interface_check
191 if that file exists. If not used in an activated workspace, or if
192 $CODEMGR_WS/exception_list/interface_check does not exist,
193 .I interface_check
194 will use
195 .I /opt/onbld/etc/exception_list/interface_check
196 as a fallback default exception file.
197 .p
198 To run
199 .I interface_check
200 without applying exceptions, specify \fB-e\fP with a value of /dev/null.
201 .P
202 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,
204 and lines containing only comments, are ignored by
205 .I interface_check.
206 Exceptions are specified as space separated keyword, and \fBperl(1)\fP
207 regular expression:
208 .sp
209 .in +4
210 .nf
211 keyword perl-regex
212 .fi
213 .in -4
214 .sp
215 Since whitespace is used as a separator, the regular
216 expression cannot itself contain whitespace. Use of the \\s character
217 class to represent whitespace within the regular expression is recommended.
218 Before the perl regular expression is used, constructs of the form
219 MACH(dir) are expanded into a regular expression that matches the directory
220 given, as well as any 64-bit architecture subdirectory that
221 might be present (i.e. amd64, sparcv9). For instance, MACH(lib) will
222 match any of the following:
223 .sp
224 .in +4
225 .nf
226 lib
227 lib/amd64
228 lib/sparcv9
229 .fi
230 .in -4
231 .sp
232 The exceptions understood by
233 .I interface_check
234 are:
235 .sp
236 .ne 2
237 .mk
238 .na
239 \fBNONSTD_VERNAME\fR
240 .ad
241 .RS 17n
242 .rt
243 .sp
244 Objects that are allowed to deviate from our standard version names.
245 .RE
246
247 .sp
248 .ne 2
249 .mk
250 .na
251 \fBNOVERDEF\fR
252 .ad
253 .RS 17n
254 .rt
255 Objects that are not expected to contain versioning information.
256 Note that PLUGIN objects are automatically exempt from this,
257 so these directives are generally applied to non-plugin objects
258 .RE
259
260 .sp
261 .ne 2
262 .mk
263 .na
264 \fBPLUGIN\fR
265 .ad
266 .RS 17n
267 .rt
268 Sharable objects underneath these parts of the tree are taken to be plugins.
269 Plugins are not required to have versioned file names, and are not required
270 to be internally versioned.
271 .RE
272 .LP
273 .SH INTERFACE DESCRIPTION FILE FORMAT
274 When the \fB-i\fP option is used
275 .I interface_check
276 produces an \fIInterface Description File\fP that captures a description of
277 the interfaces provided by each ELF object processed.
278 .P
279 Unless the \fB-h\fP option is used,
280 .I interface_check
281 produces a header comment at the start of this file, containing a CDDL
282 block and a Sun copyright notice. The header uses '#' as a comment character
283 for the lines containing text, and also includes empty lines.
284 .P
285 Following the header comment,
286 .I interface_check
287 produces a description of the interfaces provided by each object. The
288 description of each object starts with an OBJECT directive, and follows the
289 form shown below, using /lib/amd64/libadm.so.1 as an example:
290 .sp
291 .in +4
292 .nf
293 .CR
294 OBJECT lib/amd64/libadm.so.1
295 CLASS ELFCLASS64
296 TYPE ET_DYN
297 ALIAS lib/64/libadm.so
298 ALIAS lib/64/libadm.so.1
299 ALIAS lib/amd64/libadm.so
300 ALIAS usr/lib/64/libadm.so
301 ALIAS usr/lib/64/libadm.so.1
302 ALIAS usr/lib/amd64/libadm.so
303 ALIAS usr/lib/amd64/libadm.so.1
304 TOP_VERSION SUNW_1.2 {SUNW_1.1}
305 SYMBOL read_extvtoc
306 SYMBOL write_extvtoc
307 VERSION SUNW_1.1 {SUNW_0.7}
308 VERSION SUNW_0.7
309 SYMBOL pkgdir
310 SYMBOL read_vtoc
311 SYMBOL write_vtoc
312 .fi
313 .in -4
314 .sp
315 The description for every object starts with OBJECT, CLASS, and TYPE
316 directives. Following that come ALIAS lines for every alternative name
317 by which this object is known. Every version exported by the object
318 is designated by a VERSION or TOP_VERSION directive. A TOP_VERSION is
319 a version at the top of the version inheritance chain, and VERSION
320 is used for versions lower in the chain. Inherited versions are shown
321 within {} brackets following the version name. Following each version directive
322 are SYMBOL directives, each describing a symbol defined by
323 that version.
324 .P
325 When the \fB-I\fP option is used, version inheritance is expanded,
326 such that each version includes the symbols inherited from sub-versions.
327 In this mode, the SYMBOL directive is replaced with NEW for symbols
328 defined in the version, and INHERIT for those that are inherited. Using
329 \fB-I\fP for the above example produces the following output:
330 .sp
331 .in +4
332 .nf
333 .CR
334 OBJECT lib/amd64/libadm.so.1
335 CLASS ELFCLASS64
336 TYPE ET_DYN
337 ALIAS lib/64/libadm.so
338 ALIAS lib/64/libadm.so.1
339 ALIAS lib/amd64/libadm.so
340 ALIAS usr/lib/64/libadm.so
341 ALIAS usr/lib/64/libadm.so.1
342 ALIAS usr/lib/amd64/libadm.so
343 ALIAS usr/lib/amd64/libadm.so.1
344 TOP_VERSION SUNW_1.2 {SUNW_1.1}
345 INHERIT pkgdir
346 NEW read_extvtoc
347 INHERIT read_vtoc
348 NEW write_extvtoc
349 INHERIT write_vtoc
350 VERSION SUNW_1.1 {SUNW_0.7}
351 INHERIT pkgdir
352 INHERIT read_vtoc
353 INHERIT write_vtoc
354 VERSION SUNW_0.7
355 NEW pkgdir
356 NEW read_vtoc
357 NEW write_vtoc
358 .fi
359 .in -4
360 .sp
361 The \fB-I\fP option is primary used for debugging
362 .I interface_check
363 and
364 .I interface_cmp.
365 .LP
366 .SH EXAMPLES
367 The following example uses
368 .I interface_check
369 to generate an interface database for a workspace:
370 .PP
371 .RS
372 .nf
373 % mkdir $SRC/ELF-data.$MACH
374 % interface_check -w $SRC/ELF-data.$MACH -E interface.err \
375 -i interface $ROOT
376 % ls -1R $SRC/ELF
377 interface
378 interface.err
379 .br
380 .SH FILES
381 .LP
382 .RS 5
383 $CODEMGR_WS/exception_list/interface_check
384 /opt/onbld/etc/exception_list/interface_check
385 .SH SEE ALSO
386 .BR find_elf(1ONBLD),
387 .BR interface_cmp(1ONBLD),
388 .BR ld(1),
389 .BR ldd(1),
390 .BR elfdump(1),
391 .BR pvs(1).
392 .LP
393 .TZ LLM
|
2 .\"
3 .\" CDDL HEADER START
4 .\"
5 .\" The contents of this file are subject to the terms of the
6 .\" Common Development and Distribution License (the "License").
7 .\" You may not use this file except in compliance with the License.
8 .\"
9 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
10 .\" or http://www.opensolaris.org/os/licensing.
11 .\" See the License for the specific language governing permissions
12 .\" and limitations under the License.
13 .\"
14 .\" When distributing Covered Code, include this CDDL HEADER in each
15 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
16 .\" If applicable, add the following below this CDDL HEADER, with the
17 .\" fields enclosed by brackets "[]" replaced with your own identifying
18 .\" information: Portions Copyright [yyyy] [name of copyright owner]
19 .\"
20 .\" CDDL HEADER END
21 .\"
22 .TH INTERFACE_CHECK 1ONBLD "Mar 25, 2010"
23 .SH NAME
24 interface_check \- check shared object interfaces
25 .SH SYNOPSIS
26 \fBinterface_check [-hIo] [-c vertype_module] [-E errfile] [-e exfile] [-f listfile] [-i intffile] [-w outdir] file | dir, ...\fP
27 .SH DESCRIPTION
28 The
29 .I interface_check
30 command attempts to check a number of ELF versioning attributes
31 for consistency with common build rules and practices.
32 In addition, a complete breakdown of the file's version definitions can
33 be captured using the
34 .B -i
35 option, and the interface description file created can be used with
36 .I interface_cmp
37 to audit
38 the versioning evolution of a software product.
39 These interface description files reflect the association of the shared
40 object's global symbols with recorded version definitions.
41 .LP
42 .I interface_check
43 is typically called from \fBnightly(1ONBLD)\fP when the \fB-A\fP
44 option is in effect. In this case the shared objects under
45 the associated \fIproto\fP area (\fB$ROOT\fP) are examined.
46 .I interface_check
47 can also be run standalone against any set of dynamic objects.
100 of the commitment level of the interfaces it offers. Scoped
101 objects are displayed as:
102 .sp
103 .RS 6
104 foo.so.1: scoped object contains no versions
105 .LP
106 When used with the \fI-i\fP option
107 .I interface_check
108 produces a more detailed breakdown of a shared objects versioning.
109 This interface description file provides for the release-to-release
110 auditing of interfaces,
111 and monitoring the evolution of the share objects interfaces.
112 .LP
113 These files provide a complete cross reference of version to interface
114 relationships and are the basis for
115 auditing a shared objects interfaces from release-to-release. Any
116 addition, deletion or regrouping of versioning information can be
117 detected by inspecting this database with
118 .I interface_cmp.
119 .sp
120 .SH OPTIONS
121 .LP
122 The following options are supported:
123 .TP 4
124 .B \-c vertype_module
125 By default,
126 .I interface_check
127 is customized for the versioning conventions used by the Solaris
128 OSnet code base. This specialized information, which includes
129 the recognition of the SUNW_ prefix and other special names, is
130 contained in a perl module named onbld_elfmod_vertype.pm, which
131 is delivered with the SUNWonbld tools. This module is loaded by
132 .I interface_check
133 at runtime. The \fB-c\fP option can be used to supply
134 an alternative module, customized for a different code base, allowing
135 .I interface_check
136 to operate on code from other projects. The alternative module must
137 supply the same module and calling interfaces as the standard module.
138 .TP 4
139 .B \-E errfile
160 .B \-I
161 When used with the \fB-i\fP option, the interface definition produced shows
162 expanded symbol inheritance. Each version lists the symbols inherited
163 from sub-versions. This mode is primarily of interest for debugging,
164 as it matches the format produced by the \fB-t\fP option to
165 .I interface_cmp. See INTERFACE DESCRIPTION FILE FORMAT.
166 .TP 4
167 .B \-i intffile
168 Produce an output file containing a complete interface definition for
169 the objects analyzed. This file can be used with
170 .I interface_cmp
171 to audit versioning between gates, or prior to integration within
172 a single gate. See INTERFACE DESCRIPTION FILE FORMAT.
173 .TP 4
174 .B \-o
175 Produce one-liner output, with each line of diagnostic output
176 prefixed with the object pathname.
177 .TP
178 .B -w outdir
179 Interpret the paths of all input and output files relative to \fIoutdir\fP.
180 .SH EXCEPTION FILE FORMAT
181 Exceptions to the rules enforced by
182 .I interface_check
183 are be specified using an exception file. The \fB-e\fP option is used to
184 specify an explicit exception file. Otherwise, if used in an activated
185 workspace, the default exception file is
186 $CODEMGR_WS/exception_list/interface_check
187 if that file exists. If not used in an activated workspace, or if
188 $CODEMGR_WS/exception_list/interface_check does not exist,
189 .I interface_check
190 will use
191 .I /opt/onbld/etc/exception_list/interface_check
192 as a fallback default exception file.
193 .P
194 To run
195 .I interface_check
196 without applying exceptions, specify \fB-e\fP with a value of /dev/null.
197 .P
198 A '#' character at the beginning of a line, or at any point in
199 a line when preceded by whitespace, introduces a comment. Empty lines,
200 and lines containing only comments, are ignored by
201 .I interface_check.
202 Exceptions are specified as space separated keyword, and \fBperl(1)\fP
203 regular expression:
204 .sp
205 .in +4
206 .nf
207 keyword perl-regex
208 .fi
209 .in -4
210 .sp
211 Since whitespace is used as a separator, the regular
212 expression cannot itself contain whitespace. Use of the \\s character
213 class to represent whitespace within the regular expression is recommended.
214 Before the perl regular expression is used, constructs of the form
215 MACH(dir) are expanded into a regular expression that matches the directory
216 given, as well as any 64-bit architecture subdirectory that
217 might be present (i.e. amd64, sparcv9). For instance, MACH(lib) will
218 match any of the following:
219 .sp
220 .in +4
221 .nf
222 lib
223 lib/amd64
224 lib/sparcv9
225 .fi
226 .in -4
227 .sp
228 The exceptions understood by
229 .I interface_check
230 are:
231 .sp
232 .ne 2
233 .na
234 \fBNONSTD_VERNAME\fR
235 .ad
236 .RS 17n
237 .sp
238 Objects that are allowed to deviate from our standard version names.
239 .RE
240
241 .sp
242 .ne 2
243 .na
244 \fBNOVERDEF\fR
245 .ad
246 .RS 17n
247 Objects that are not expected to contain versioning information.
248 Note that PLUGIN objects are automatically exempt from this,
249 so these directives are generally applied to non-plugin objects
250 .RE
251
252 .sp
253 .ne 2
254 .na
255 \fBPLUGIN\fR
256 .ad
257 .RS 17n
258 Sharable objects underneath these parts of the tree are taken to be plugins.
259 Plugins are not required to have versioned file names, and are not required
260 to be internally versioned.
261 .RE
262 .SH INTERFACE DESCRIPTION FILE FORMAT
263 When the \fB-i\fP option is used
264 .I interface_check
265 produces an \fIInterface Description File\fP that captures a description of
266 the interfaces provided by each ELF object processed.
267 .P
268 Unless the \fB-h\fP option is used,
269 .I interface_check
270 produces a header comment at the start of this file, containing a CDDL
271 block and a Sun copyright notice. The header uses '#' as a comment character
272 for the lines containing text, and also includes empty lines.
273 .P
274 Following the header comment,
275 .I interface_check
276 produces a description of the interfaces provided by each object. The
277 description of each object starts with an OBJECT directive, and follows the
278 form shown below, using /lib/amd64/libadm.so.1 as an example:
279 .sp
280 .in +4
281 .nf
282 OBJECT lib/amd64/libadm.so.1
283 CLASS ELFCLASS64
284 TYPE ET_DYN
285 ALIAS lib/64/libadm.so
286 ALIAS lib/64/libadm.so.1
287 ALIAS lib/amd64/libadm.so
288 ALIAS usr/lib/64/libadm.so
289 ALIAS usr/lib/64/libadm.so.1
290 ALIAS usr/lib/amd64/libadm.so
291 ALIAS usr/lib/amd64/libadm.so.1
292 TOP_VERSION SUNW_1.2 {SUNW_1.1}
293 SYMBOL read_extvtoc
294 SYMBOL write_extvtoc
295 VERSION SUNW_1.1 {SUNW_0.7}
296 VERSION SUNW_0.7
297 SYMBOL pkgdir
298 SYMBOL read_vtoc
299 SYMBOL write_vtoc
300 .fi
301 .in -4
302 .sp
303 The description for every object starts with OBJECT, CLASS, and TYPE
304 directives. Following that come ALIAS lines for every alternative name
305 by which this object is known. Every version exported by the object
306 is designated by a VERSION or TOP_VERSION directive. A TOP_VERSION is
307 a version at the top of the version inheritance chain, and VERSION
308 is used for versions lower in the chain. Inherited versions are shown
309 within {} brackets following the version name. Following each version directive
310 are SYMBOL directives, each describing a symbol defined by
311 that version.
312 .P
313 When the \fB-I\fP option is used, version inheritance is expanded,
314 such that each version includes the symbols inherited from sub-versions.
315 In this mode, the SYMBOL directive is replaced with NEW for symbols
316 defined in the version, and INHERIT for those that are inherited. Using
317 \fB-I\fP for the above example produces the following output:
318 .sp
319 .in +4
320 .nf
321 OBJECT lib/amd64/libadm.so.1
322 CLASS ELFCLASS64
323 TYPE ET_DYN
324 ALIAS lib/64/libadm.so
325 ALIAS lib/64/libadm.so.1
326 ALIAS lib/amd64/libadm.so
327 ALIAS usr/lib/64/libadm.so
328 ALIAS usr/lib/64/libadm.so.1
329 ALIAS usr/lib/amd64/libadm.so
330 ALIAS usr/lib/amd64/libadm.so.1
331 TOP_VERSION SUNW_1.2 {SUNW_1.1}
332 INHERIT pkgdir
333 NEW read_extvtoc
334 INHERIT read_vtoc
335 NEW write_extvtoc
336 INHERIT write_vtoc
337 VERSION SUNW_1.1 {SUNW_0.7}
338 INHERIT pkgdir
339 INHERIT read_vtoc
340 INHERIT write_vtoc
341 VERSION SUNW_0.7
342 NEW pkgdir
343 NEW read_vtoc
344 NEW write_vtoc
345 .fi
346 .in -4
347 .sp
348 The \fB-I\fP option is primary used for debugging
349 .I interface_check
350 and
351 .I interface_cmp.
352 .SH EXAMPLES
353 The following example uses
354 .I interface_check
355 to generate an interface database for a workspace:
356 .PP
357 .RS
358 .nf
359 % mkdir $SRC/ELF-data.$MACH
360 % interface_check -w $SRC/ELF-data.$MACH -E interface.err \
361 -i interface $ROOT
362 % ls -1R $SRC/ELF
363 interface
364 interface.err
365 .br
366 .SH FILES
367 .LP
368 .RS 5
369 $CODEMGR_WS/exception_list/interface_check
370 /opt/onbld/etc/exception_list/interface_check
371 .SH SEE ALSO
372 .BR find_elf(1ONBLD),
373 .BR interface_cmp(1ONBLD),
374 .BR ld(1),
375 .BR ldd(1),
376 .BR elfdump(1),
377 .BR pvs(1).
378
379
|