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