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. To run interface_check without
143 applying exceptions, specify -e with a value of /dev/null.
144
145 A '#' character at the beginning of a line, or at any point in a line
146 when preceded by whitespace, introduces a comment. Empty lines, and
147 lines containing only comments, are ignored by interface_check.
148 Exceptions are specified as space separated keyword, and perl(1)
149 regular expression:
150
151 keyword perl-regex
152
153 Since whitespace is used as a separator, the regular expression cannot
154 itself contain whitespace. Use of the \s character class to represent
155 whitespace within the regular expression is recommended. Before the
156 perl regular expression is used, constructs of the form MACH(dir) are
157 expanded into a regular expression that matches the directory given, as
158 well as any 64-bit architecture subdirectory that might be present
159 (i.e. amd64, sparcv9). For instance, MACH(lib) will match any of the
160 following:
161
162 lib
163 lib/amd64
164 lib/sparcv9
165
166 The exceptions understood by interface_check are:
167
168 NONSTD_VERNAME
169
170 Objects that are allowed to deviate from our standard
171 version names.
172
173
174 NOVERDEF
175 Objects that are not expected to contain versioning
176 information. Note that PLUGIN objects are
177 automatically exempt from this, so these directives
178 are generally applied to non-plugin objects
179
180
181 PLUGIN
182 Sharable objects underneath these parts of the tree
183 are taken to be plugins. Plugins are not required to
184 have versioned file names, and are not required to be
185 internally versioned.
186
187 INTERFACE DESCRIPTION FILE FORMAT
188 When the -i option is used interface_check produces an Interface
189 Description File that captures a description of the interfaces provided
190 by each ELF object processed.
191
192 Unless the -h option is used, interface_check produces a header comment
193 at the start of this file, containing a CDDL block and a Sun copyright
194 notice. The header uses '#' as a comment character for the lines
195 containing text, and also includes empty lines.
196
197 Following the header comment, interface_check produces a description of
198 the interfaces provided by each object. The description of each object
199 starts with an OBJECT directive, and follows the form shown below,
200 using /lib/amd64/libadm.so.1 as an example:
201
202 OBJECT lib/amd64/libadm.so.1
203 CLASS ELFCLASS64
204 TYPE ET_DYN
205 ALIAS lib/64/libadm.so
206 ALIAS lib/64/libadm.so.1
207 ALIAS lib/amd64/libadm.so
208 ALIAS usr/lib/64/libadm.so
209 ALIAS usr/lib/64/libadm.so.1
210 ALIAS usr/lib/amd64/libadm.so
211 ALIAS usr/lib/amd64/libadm.so.1
212 TOP_VERSION SUNW_1.2 {SUNW_1.1}
213 SYMBOL read_extvtoc
214 SYMBOL write_extvtoc
215 VERSION SUNW_1.1 {SUNW_0.7}
216 VERSION SUNW_0.7
217 SYMBOL pkgdir
218 SYMBOL read_vtoc
219 SYMBOL write_vtoc
220
221 The description for every object starts with OBJECT, CLASS, and TYPE
222 directives. Following that come ALIAS lines for every alternative name
223 by which this object is known. Every version exported by the object is
224 designated by a VERSION or TOP_VERSION directive. A TOP_VERSION is a
225 version at the top of the version inheritance chain, and VERSION is
226 used for versions lower in the chain. Inherited versions are shown
227 within {} brackets following the version name. Following each version
228 directive are SYMBOL directives, each describing a symbol defined by
229 that version.
230
231 When the -I option is used, version inheritance is expanded, such that
232 each version includes the symbols inherited from sub-versions. In this
233 mode, the SYMBOL directive is replaced with NEW for symbols defined in
234 the version, and INHERIT for those that are inherited. Using -I for the
235 above example produces the following output:
236
237 OBJECT lib/amd64/libadm.so.1
238 CLASS ELFCLASS64
239 TYPE ET_DYN
240 ALIAS lib/64/libadm.so
241 ALIAS lib/64/libadm.so.1
242 ALIAS lib/amd64/libadm.so
243 ALIAS usr/lib/64/libadm.so
244 ALIAS usr/lib/64/libadm.so.1
245 ALIAS usr/lib/amd64/libadm.so
246 ALIAS usr/lib/amd64/libadm.so.1
247 TOP_VERSION SUNW_1.2 {SUNW_1.1}
248 INHERIT pkgdir
249 NEW read_extvtoc
250 INHERIT read_vtoc
251 NEW write_extvtoc
252 INHERIT write_vtoc
253 VERSION SUNW_1.1 {SUNW_0.7}
254 INHERIT pkgdir
255 INHERIT read_vtoc
256 INHERIT write_vtoc
257 VERSION SUNW_0.7
258 NEW pkgdir
259 NEW read_vtoc
260 NEW write_vtoc
261
262 The -I option is primary used for debugging interface_check and
263 interface_cmp.
264
265 EXAMPLES
266 The following example uses interface_check to generate an interface
267 database for a workspace:
268
269 % mkdir $SRC/ELF-data.$MACH
270 % interface_check -w $SRC/ELF-data.$MACH -E interface.err
271 -i interface $ROOT
272 % ls -1R $SRC/ELF
273 interface
274 interface.err
275
276 FILES
277 $CODEMGR_WS/exception_list/interface_check
278 /opt/onbld/etc/exception_list/interface_check
279
280 SEE ALSO
281 find_elf(1ONBLD), interface_cmp(1ONBLD), ld(1), ldd(1), elfdump(1),
282 pvs(1).
283
284
285
286 25 March 2010 interface_check(1ONBLD)