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