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