1 .\" Copyright (c) 2009, 2010, Oracle and/or its affiliates. All rights reserved.
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.
50 .LP
51 .I interface_check
52 uses \fBelfdump(1)\fP and \fBpvs(1)\fP to
53 check file naming standardization, and versioning consistency. These
54 check are carried out for the following reasons:
55 .TP 4
56 \(bu
57 A shared object should exist with a versioned filename.
58 A versioned filename commonly takes the form of a \fI.so\fP suffix
59 followed by a version number. For example, \fI/usr/lib/libc.so.1\fP
60 is the shared object representation of version one of the standard C
61 library made available to the runtime environment.
62 A versioned filename allows for a change in the exported interface of
63 the shared object over a series of software releases. A shared object
64 that doesn't exist as a versioned filename is displayed as:
65 .sp
66 .RS 6
67 foo.so: does not have a versioned name
68 .RE
69 .TP
70 \(bu
71 Versions should be defined within a shared object both to clarify its
72 public or private use, and to explicitly define the interfaces that it
73 makes available. The reduction in object size, and relocation cost
74 created by reducing non-interface symbols to locals is an added bonus.
75 A non-versioned shared object is displayed as:
76 .sp
77 .RS 6
78 foo.so.1: no versions found
79 .RE
80 .TP
81 \(bu
82 Version definitions should follow a standard naming convention, i.e.,
83 \fBSUNW_\fIx.y\fP\fP, \fBSUNWprivate_\fIx.y\fP\fP, or \fIfilename\fP. The
84 latter version is a base version and is used to capture any reserved
85 interface symbols (i.e., \fI_end\fP, \fI_etext\fP, etc.). Any non-conforming
86 version names are displayed as:
87 .sp
88 .RS 6
89 foo.so.1: non-standard version name: \fIversion-name\fP
90 .RE
91 .sp
92 .RS 4
93 Note, that non-conforming base version names are often generated when
94 the file itself has an internal identification that differs from the
95 actual filename (see \fBld(1)\fP \fI-h\fP).
96 .RE
97 .TP
98 \(bu
99 A scoped object, one that has defined its external interfaces
100 and whose internal interfaces have been reduced to locals,
101 but has no version definitions assigned, does not inform users
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
143 Direct error messages for the analyzed objects to \fIerrfile\fP instead
144 of stdout.
145 .TP 4
146 .B \-e exfile
147 An exception file is used to exclude objects from
148 the usual rules. See EXCEPTION FILE FORMAT.
149 .TP 4
150 .B \-f listfile
151 Normally,
152 .I interface_check
153 runs
154 .I find_elf
155 to locate the ELF objects to analyze. The \fB-f\fP option can be
156 used to instead provide a file containing the list of objects to
157 analyze, in the format produced by '\fBfind_elf -r\fP'.
158 .TP 4
159 .B \-h
160 Prevent the generation of the CDDL license and Sun copyright header
161 normally produced at the start of output.
162 .TP 4
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