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