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/check_rtime.1onbld.man.txt
+++ new/usr/src/tools/scripts/check_rtime.1onbld.man.txt
1 -check_rtime(1ONBLD) illumos Build Tools check_rtime(1ONBLD)
1 +CHECK_RTIME(1ONBLD) illumos Build Tools CHECK_RTIME(1ONBLD)
2 2
3 3
4 4
5 5 NAME
6 6 check_rtime - check ELF runtime attributes
7 7
8 8 SYNOPSIS
9 9 check_rtime [-imosv] [-D depfile | -d depdir] [-E errfile] [-e exfile]
10 10 [-f listfile] [-I infofile] [-w outdir] file | dir, ...
11 11
12 12 DESCRIPTION
13 13 check_rtime attempts to check a number of ELF runtime attributes for
14 14 consistency with common build rules. These checks involve running
15 15 ldd(1) and elfdump(1) against a family of dynamic objects. A dynamic
16 16 object can be defined explicitly as a file or multiple dynamic objects
17 17 can be located under the directory dir.
18 18
19 19 check_rtime is typically called from nightly(1ONBLD) when the -r option
20 20 is in effect. In this case the dynamic objects under the associated
21 21 proto area ($ROOT) are checked. check_rtime can also be run standalone
22 22 against any set of dynamic objects.
23 23
24 24 check_rtime uses ldd(1) to verify dependencies. This implies that by
25 25 default any object inspected will bind to its dependencies as they are
26 26 found in the underlying system. Use of the -D, -d option, or the
27 27 existence of the environment variables $CODEMGR_WS/$ROOT instruct
28 28 check_rtime to establish an alternative dependency mapping using
29 29 runtime configuration files generated with crle(1).
30 30
31 31 check_rtime uses ldd(1) to completely relocate any dynamic object and
32 32 thus detect missing dependencies, unsatisfied symbol relocations,
33 33 unused and unreferenced dependencies. These checks are carried out for
34 34 the following reasons:
35 35
36 36 o An object that cannot find its dependencies may fail to load at
37 37 runtime. This error condition often goes unnoticed because the
38 38 existing use of the object is as a dependency itself, and the
39 39 objects' dependencies are already satisfied by the caller.
40 40 However, if the object itself is unable to satisfy its
41 41 dependencies, its use in new environments may be compromised.
42 42
43 43 A missing or erroneous runpath is the typical reason why an object
44 44 can not locate its dependencies. Use of the link-editors -zdefs
45 45 option when building a shared object ensures required dependencies
46 46 are established. This flag is inherited from $(DYNFLAGS) in
47 47 lib/Makefile.lib. Missing dependencies are displayed as:
48 48
49 49 foo: bar.so.1 => (file not found) <no -zdefs?>
50 50
51 51 o Unsatisfied symbol relocations indicate that some thread of
52 52 execution through the object will fail when it is unable to locate
53 53 a referenced symbol.
54 54
55 55 A missing, or mismatched version of a dependency is the typical
56 56 reason for unsatisfied symbol relocations (see missing dependency
57 57 discussion above). Unsatisfied symbol relocations are displayed as:
58 58
59 59 foo: symbol not found: bar <no -zdefs?>
60 60
61 61 Note: Shared objects can make reference to symbol definitions that
62 62 are expected to be defined by the caller. To indicate that such
63 63 symbols are not undefined in the usual sense, you must specify
64 64 these symbols in a mapfile, using the EXTERN or PARENT symbol
65 65 attribute. Without these symbol attributes, ldd(1) is unable to
66 66 determine the symbols special nature, and check_rtime will report
67 67 these symbols as undefined.
68 68
69 69 o Unused dependencies are wasteful at runtime, as they take time to
70 70 load and relocate, but will not be used by the calling object.
71 71 They also result in unnecessary processing at link-edit time.
72 72
73 73 Dependency lists (typically defined via $(LDLIBS)) that have been
74 74 yanked-and-put between Makefiles without verifying their need, are
75 75 a typical reason why unused dependencies exist. Unused
76 76 dependencies are displayed as:
77 77
78 78 foo: unused object=bar.so.1 <remove lib or -zignore?>
79 79
80 80 o Unreferenced dependencies are also wasteful at runtime, although
81 81 not to the extent of unused dependencies. They also result in
82 82 unnecessary processing at link-edit time.
83 83
84 84 Unreferenced dependency removal guards against a dependency
85 85 becoming unused when combined with different objects, or as the
86 86 other object dependencies evolve. Unreferenced dependencies are
87 87 displayed as:
88 88
89 89 foo: unreferenced object=bar.so.1; \
90 90 unused dependency of libfoo.so.1 \
91 91 <remove lib or -zignore?>
92 92
93 93 See also the section ENVIRONMENT VARIABLES.
94 94
95 95 o Unused search paths are wasteful at runtime. Unused search paths
96 96 are displayed as:
97 97
98 98 foo: unused search path=/usr/foo/lib \
99 99 (RUNPATH/RPATH from file libfoo.so.1) \
100 100 <remove search path?>
101 101
102 102 check_rtime uses elfdump(1) to look for a concatenated relocation
103 103 section in shared objects, the existence of text relocations, whether
104 104 debugging or symbol table information exists, whether applications have
105 105 a non-executable stack defined, duplicate entries in the symbol sorting
106 106 sections, and for direct bindings. These checks are carried out for
107 107 the following reasons:
108 108
109 109 o A concatenated relocation section (.SUNW_reloc) provides optimal
110 110 symbol table access at runtime, and thus reduces the overhead of
111 111 relocating the shared object. In past releases, the link-edit of a
112 112 dynamic object with the -z combreloc option was required to
113 113 generate a combined relocation section. However, with the
114 114 integration of 6642769, this section combination is a default
115 115 behavior of the link-editor.
116 116
117 117 In past releases, not inheriting $(DYNFLAGS) from lib/Makefile.lib
118 118 was the typical reason for not having a concatenated relocation
119 119 section. The misguided use of the -z nocombreloc option will also
120 120 prevent the creation of a concatenated relocation section. A
121 121 missing concatenated relocation section is displayed as:
122 122
123 123 foo: .SUNW_reloc section missing <no -zcombreloc?>
124 124
125 125 o Text relocations result in impure text segments. As text segments
126 126 are typically read-only, they can be shared between numerous
127 127 processes. If they must be updated as part of the relocation then
128 128 the updated pages become unsharable and swap space must be
129 129 allocated to back these pages. These events consume unnecessary
130 130 system resources and reduce overall system performance.
131 131
132 132 Not inheriting the $(PICS) rules from lib/Makefile.lib is the
133 133 typical reason for having non-pic code in shared objects. Text
134 134 relocations are displayed as:
135 135
136 136 foo: TEXTREL .dynamic tag <no -Kpic?>
137 137
138 138 o Debugging information is unnecessary in released objects. Although
139 139 extensive when compiled -g, small quantities of debugging
140 140 information are stored in .stabs sections under normal
141 141 compilations. This debugging information is geared towards aiding
142 142 debuggers locate relocatable objects associated with the dynamic
143 143 objects being debugged. As relocatable objects aren't made
144 144 available as part of a software release this information has no
145 145 use.
146 146
147 147 Not inheriting the correct $(LDFLAGS) from cmd/Makefile.cmd (which
148 148 asserts -s), or $(POST_PROCESS_SO) (which asserts strip -x) are
149 149 typical reasons for not removing debugging information. Note,
150 150 removal of debugging information is only enabled for release
151 151 builds. The existence of debugging information is displayed as:
152 152
153 153 foo: debugging sections should be deleted \
154 154 <no strip -x?>
155 155
156 156 o All objects should retain their full .symtab symbol table.
157 157 Although this consumes disk space, it provides for more extensive
158 158 stack tracing when debugging user applications.
159 159
160 160 Hard coding a -s flag with $(LDFLAGS) or $(DYNFLAGS) is the typical
161 161 reason for symbol tables being removed. Objects that do not
162 162 contain a symbol table are displayed as:
163 163
164 164 foo.so.1: symbol table should not be stripped \
165 165 <remove -s?>
166 166
167 167 o Applications should have a non-executable stack defined to make
168 168 them less vulnerable to buffer overflow attacks.
169 169
170 170 Not inheriting the $(LDFLAGS) macro in cmd/Makefile.cmd is the
171 171 typical reason for not having a non-executable stack definition.
172 172 Applications without this definition are displayed as:
173 173
174 174 foo: application requires non-executable stack \
175 175 <no -Mmapfile_noexstk?>
176 176
177 177
178 178 o x86 applications should have a non-executable data segment defined
179 179 to make them less vulnerable to buffer overflow attacks.
180 180
181 181 Not inheriting the $(LDFLAGS) macro in cmd/Makefile.cmd is the
182 182 typical reason for not having a non-executable data definition.
183 183 Applications without this definition are displayed as:
184 184
185 185 foo: application requires non-executable data \
186 186 <no -Mmapfile_noexdata?>
187 187
188 188
189 189 o Solaris ELF files contain symbol sort sections used by DTrace to
190 190 map addresses in memory to the related function or variable
191 191 symbols. There are two such sections, .SUNW_dynsymsort for regular
192 192 symbols, and .SUNW_dyntlssort for thread-local symbols. To ensure
193 193 that the best names are shown for each such address, and that the
194 194 same name is given across Solaris releases, check_rtime enforces
195 195 the rule that only one symbol can appear in the sort sections for
196 196 any given address. There are two common ways in which multiple
197 197 symbols or a given address occur in the ON distribution. The first
198 198 is from code written in assembly language. The second is as a
199 199 result of using #pragma weak in C to create weak symbols. The best
200 200 solution to this situation is to modify the code to avoid symbol
201 201 aliasing. Alternatively, the NODYNSORT mapfile attribute can be
202 202 used to eliminate the unwanted symbol.
203 203
204 204 Duplicate entries in a symbol sort section are displayed in one of
205 205 the following ways, depending on whether the section is for regular
206 206 or thread-local symbols:
207 207
208 208 foo: .SUNW_dynsymsort: duplicate ADDRESS: sym1, sym2
209 209 foo: .SUNW_dyntlssort: duplicate OFFSET: sym1, sym2
210 210
211 211
212 212 o OSNet dynamic ELF objects are expected to employ direct bindings
213 213 whenever feasible. This runtime binding technique helps to avoid
214 214 accidental interposition problems, and provides a more optimal
215 215 runtime symbol search model.
216 216
217 217 Not inheriting the correct $(LDFLAGS) from cmd/Makefile.cmd, or the
218 218 correct $(DYNFLAGS) from lib/Makefile.lib, are the typical reasons
219 219 for not enabling direct bindings. Dynamic objects that do not
220 220 contain direct binding information are displayed as:
221 221
222 222 foo: object has no direct bindings \
223 223 <no -B direct or -z direct?>
224 224
225 225
226 226
227 227 check_rtime also uses elfdump(1) to display useful dynamic entry
228 228 information under the -i option. This doesn't necessarily indicate an
229 229 error condition, but provides information that is often useful for
230 230 gatekeepers to track changes in a release. Presently the information
231 231 listed is:
232 232
233 233 o Runpaths are printed for any dynamic object. This is a historic
234 234 sanity check to insure compiler supplied runpaths (typically
235 235 from CC) are not recorded in any objects. Runpaths are
236 236 displayed as:
237 237
238 238 foo: RPATH=/usr/bar/lib
239 239
240 240 o Needed dependencies are printed for any dynamic object. In the
241 241 freeware world this often helps the introducer of a new shared
242 242 object discover that an existing binary has become its consumer,
243 243 and thus that binaries package dependencies may require
244 244 updating. Dependencies are printed as:
245 245
246 246 foo: NEEDED=bar.so.1
247 247
248 248
249 249 check_rtime uses mcs(1) to inspect an object's .comment section.
250 250 During development, this section contains numerous file identifiers
251 251 marked with the tag "@(#)". For release builds these sections are
252 252 deleted and rewritten under control of the $(POST_PROCESS) macro to
253 253 produce a common release identifier. This identifier typically
254 254 consists of three lines including a single comment starting with the
255 255 string "@(#) SunOS". If this common identifier isn't found the
256 256 following diagnostic is generated:
257 257
258 258 foo: non-conforming mcs(1) comment <no $(POST_PROCESS)?>
259 259
260 260
261 261 check_rtime uses pvs(1) to display version definitions under the -v
262 262 option. Each symbol defined by the object is shown along with the
263 263 version it belongs to. Changes to the symbols defined by an object, or
264 264 the versions they belong to, do not necessarily indicate an error
265 265 condition, but provides information that is often useful for
266 266 gatekeepers to track changes in a release.
267 267
268 268
269 269 OPTIONS
270 270 The following options are supported:
271 271
272 272 -D depfile
273 273 Use depfile to generate an alternative dependency mapping. depfile
274 274 must be created by 'find_elf -r'. The -D and -d options are
275 275 mutually exclusive.
276 276
277 277 -d depdir
278 278 Use depdir to generate an alternative dependency mapping.
279 279 find_elf(1ONBLD) is used to locate the ELF sharable objects for
280 280 which alternative mappings are required. The -D and -d options are
281 281 mutually exclusive.
282 282
283 283 -E errfile
284 284 Direct error messages for the analyzed objects to errfile instead
285 285 of stdout.
286 286
287 287 -e exfile
288 288 An exception file is used to exclude objects from the usual rules.
289 289 See EXCEPTION FILE FORMAT.
290 290
291 291 -f listfile
292 292 Normally, interface_check runs find_elf to locate the ELF objects
293 293 to analyze. The -f option can be used to instead provide a file
294 294 containing the list of objects to analyze, in the format produced
295 295 by 'find_elf -r'.
296 296
297 297 -I infofile
298 298 Direct informational messages (-i, and -v options) for the analyzed
299 299 objects to infofile instead of stdout.
300 300
301 301 -i Provide dynamic entry information. Presently only dependencies and
302 302 runpaths are printed.
303 303
304 304 -m Enable mcs(1) checking.
305 305
306 306 -o Produce a one-line output for each condition discovered, prefixed
307 307 by the objects name. This output style is more terse, but is more
308 308 appropriate for sorting and diffing with previous build results.
309 309
310 310 -s Determine whether .stabs sections exist.
311 311
312 312 -v Provide version definition information. Each symbol defined by the
313 313 object is printed along with the version it is assigned to.
314 314
315 315 -w outdir
316 316 Interpret the paths of all input and output files relative to
|
↓ open down ↓ |
305 lines elided |
↑ open up ↑ |
317 317 outdir.
318 318
319 319 EXCEPTION FILE FORMAT
320 320 Exceptions to the rules enforced by check_rtime are specified using an
321 321 exception file. The -e option is used to specify an explicit exception
322 322 file. Otherwise, if used in an activated workspace, the default
323 323 exception file is $CODEMGR_WS/exception_list/check_rtime if that file
324 324 exists. If not used in an activated workspace, or if
325 325 $CODEMGR_WS/exception_list/check_rtime does not exist, check_rtime will
326 326 use /opt/onbld/etc/exception_list/check_rtime as a fallback default
327 - exception file. To run check_rtime without applying exceptions,
328 - specify -e with a value of /dev/null.
327 + exception file.
329 328
329 + To run check_rtime without applying exceptions, specify -e with a value
330 + of /dev/null.
331 +
330 332 A '#' character at the beginning of a line, or at any point in a line
331 333 when preceded by whitespace, introduces a comment. Empty lines, and
332 334 lines containing only comments, are ignored by check_rtime. Exceptions
333 335 are specified as space separated keyword, and perl(1) regular
334 336 expression:
335 337
336 338 keyword perl-regex
337 339
338 340 Since whitespace is used as a separator, the regular expression cannot
339 341 itself contain whitespace. Use of the \s character class to represent
340 342 whitespace within the regular expression is recommended. Before the
341 343 perl regular expression is used, constructs of the form MACH(dir) are
342 344 expanded into a regular expression that matches the directory given, as
343 345 well as any 64-bit architecture subdirectory that might be present
344 346 (i.e. amd64, sparcv9). For instance, MACH(lib) will match any of the
345 347 following:
346 348
347 349 lib
348 350 lib/amd64
349 351 lib/sparcv9
350 352
351 353 The exceptions understood by check_rtime are:
352 354
353 355 EXEC_DATA
354 356
355 357 Executables that are not required to have non-
356 358 executable writable data segments
357 359
358 360
359 361 EXEC_STACK
360 362
361 363 Executables that are not required to have a non-
362 364 executable stack
363 365
364 366
365 367 NOCRLEALT
366 368
367 369 Objects that should be skipped when building the
368 370 alternative dependency mapping via the -d option.
369 371
370 372
371 373 NODIRECT
372 374
373 375 Directories and files that are allowed to have no
374 376 direct bound symbols.
375 377
376 378
377 379 NOSYMSORT
378 380
379 381 Files for which we skip checking of duplicate
380 382 addresses in the symbol sort sections.
381 383
382 384
383 385 OLDDEP
384 386
385 387 Objects that used to contain system functionality that
386 388 has since migrated to libc. We preserve these
387 389 libraries as pure filters for backward compatibility
388 390 but nothing needs to link to them.
389 391
390 392
391 393 SKIP
392 394
393 395 Directories and/or individual objects to skip. Note
394 396 that SKIP should be a last resort, used only when one
395 397 of the other exceptions will not suffice.
396 398
397 399
398 400 STAB
399 401
400 402 Objects that are allowed to contain debugging
401 403 information (stabs).
402 404
403 405
404 406 TEXTREL
405 407
406 408 Objects for which we allow relocations to the text
407 409 segment.
408 410
409 411
410 412 UNDEF_OBJ
411 413
412 414 Objects that are allowed to be unreferenced.
413 415
414 416
415 417 UNDEF_REF
416 418
417 419 Objects that are allowed undefined references.
418 420
419 421
420 422 UNUSED_DEPS
421 423
422 424 Objects that are allowed to have unused dependencies.
423 425
424 426
425 427 UNUSED_OBJ
426 428
427 429 Objects that are always allowed to be unused
428 430 dependencies.
429 431
430 432
431 433 UNUSED_RPATH
432 434
433 435 Objects that are allowed to have unused runpath
434 436 directories.
435 437
436 438
437 439 ALTERNATIVE DEPENDENCY MAPPING
438 440 check_rtime was primarily designed to process a nightly builds $ROOT
439 441 hierarchy. It is often the case that objects within this hierarchy must
440 442 bind to dependencies within the same hierarchy to satisfy their
441 443 requirements.
442 444
443 445 To achieve this, check_rtime uses the shared objects specified with the
444 446 -D or -d options. If neither option is specified, and the $CODEMGR_WS
445 447 and $ROOT environment variables are defined, the proto area for the
446 448 workspace is used. The objects found are used to create runtime
447 449 configuration files via crle(1), that establish the new shared objects
448 450 as alternatives to their underlying system location. check_rtime
449 451 passes these configuration files as LD_CONFIG environment variable
450 452 settings to ldd(1) using its -e option.
451 453
452 454 The effect of these configuration files is that the execution of an
453 455 object under ldd(1) will bind to the dependencies defined as
454 456 alternatives. Simply put, an object inspected in the proto area will
455 457 bind to its dependencies found in the proto area. Dependencies that
456 458 have no alternative mapping will continue to bind to the underlying
457 459 system.
458 460
459 461 ENVIRONMENT VARIABLES
460 462 When the -D or -d option isn't in use, check_rtime uses the following
461 463 environment variables to establish an alternative dependency mapping:
462 464
463 465 CODEMGR_WS
464 466 The root of your workspace, which is the directory containing
465 467 Codemgr_wsdata. Existence of this environment variable indicates
466 468 that $ROOT should be investigated.
467 469
468 470 ROOT
469 471 Root of the proto area of your workspace. Any shared objects under
470 472 this directory will be used to establish an alternative dependency
471 473 mapping.
472 474
473 475 If ldd(1) supports the -U option, it will be used to determine any
474 476 unreferenced dependencies. Otherwise ldd(1) uses the older -u option
475 477 which only detects unused references. If the following environment
476 478 variable exists, and indicates an earlier release than 5.10 then ldd(1)
477 479 also falls back to using the -u option.
478 480
479 481 RELEASE
480 482 The release version number of the environment being built.
481 483
482 484 ERROR CONDITIONS
483 485 Inspection of an object with ldd(1) assumes it is compatible with the
484 486 machine on which check_rtime is being run. Incompatible objects such
485 487 as a 64-bit object encountered on a 32-bit system, or an i386 object
486 488 encountered on a sparc system, can not be fully inspected. These
487 489 objects are displayed as:
488 490
489 491 foo: has wrong class or data encoding
|
↓ open down ↓ |
150 lines elided |
↑ open up ↑ |
490 492
491 493 FILES
492 494 $CODEMGR_WS/exception_list/check_rtime
493 495 /opt/onbld/etc/exception_list/check_rtime
494 496
495 497 SEE ALSO
496 498 crle(1), elfdump(1), find_elf(1ONBLD), ldd(1), ld.so.1(1), mcs(1).
497 499
498 500
499 501
500 - 09 March 2010 check_rtime(1ONBLD)
502 + March 9, 2010 CHECK_RTIME(1ONBLD)
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX