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/check_rtime.1.man.txt
+++ new/usr/src/tools/scripts/check_rtime.1onbld.man.txt
1 -check_rtime(1) User Commands check_rtime(1)
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 - check_rtime is typically called from nightly(1) when the -r option is
20 - in effect. In this case the dynamic objects under the associated proto
21 - area ($ROOT) are checked. check_rtime can also be run standalone
19 + check_rtime is typically called from nightly(1ONBLD) when the -r option
20 + is in effect. In this case the dynamic objects under the associated
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
|
↓ open down ↓ |
237 lines elided |
↑ open up ↑ |
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 - find_elf(1) is used to locate the ELF sharable objects for which
280 - alternative mappings are required. The -D and -d options are
279 + find_elf(1ONBLD) is used to locate the ELF sharable objects for
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
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 327 exception file. To run check_rtime without applying exceptions,
328 328 specify -e with a value of /dev/null.
329 329
330 330 A '#' character at the beginning of a line, or at any point in a line
331 331 when preceded by whitespace, introduces a comment. Empty lines, and
332 332 lines containing only comments, are ignored by check_rtime. Exceptions
333 333 are specified as space separated keyword, and perl(1) regular
334 334 expression:
335 335
336 336 keyword perl-regex
337 337
338 338 Since whitespace is used as a separator, the regular expression cannot
339 339 itself contain whitespace. Use of the \s character class to represent
340 340 whitespace within the regular expression is recommended. Before the
341 341 perl regular expression is used, constructs of the form MACH(dir) are
342 342 expanded into a regular expression that matches the directory given, as
343 343 well as any 64-bit architecture subdirectory that might be present
344 344 (i.e. amd64, sparcv9). For instance, MACH(lib) will match any of the
345 345 following:
346 346
347 347 lib
348 348 lib/amd64
349 349 lib/sparcv9
350 350
351 351 The exceptions understood by check_rtime are:
352 352
353 353 EXEC_DATA
354 354
355 355 Executables that are not required to have non-
356 356 executable writable data segments
357 357
358 358
359 359 EXEC_STACK
360 360
361 361 Executables that are not required to have a non-
362 362 executable stack
363 363
364 364
365 365 NOCRLEALT
366 366
367 367 Objects that should be skipped when building the
368 368 alternative dependency mapping via the -d option.
369 369
370 370
371 371 NODIRECT
372 372
373 373 Directories and files that are allowed to have no
374 374 direct bound symbols.
375 375
376 376
377 377 NOSYMSORT
378 378
379 379 Files for which we skip checking of duplicate
380 380 addresses in the symbol sort sections.
381 381
382 382
383 383 OLDDEP
384 384
385 385 Objects that used to contain system functionality that
386 386 has since migrated to libc. We preserve these
387 387 libraries as pure filters for backward compatibility
388 388 but nothing needs to link to them.
389 389
390 390
391 391 SKIP
392 392
393 393 Directories and/or individual objects to skip. Note
394 394 that SKIP should be a last resort, used only when one
395 395 of the other exceptions will not suffice.
396 396
397 397
398 398 STAB
399 399
400 400 Objects that are allowed to contain debugging
401 401 information (stabs).
402 402
403 403
404 404 TEXTREL
405 405
406 406 Objects for which we allow relocations to the text
407 407 segment.
408 408
409 409
410 410 UNDEF_OBJ
411 411
412 412 Objects that are allowed to be unreferenced.
413 413
414 414
415 415 UNDEF_REF
416 416
417 417 Objects that are allowed undefined references.
418 418
419 419
420 420 UNUSED_DEPS
421 421
422 422 Objects that are allowed to have unused dependencies.
423 423
424 424
425 425 UNUSED_OBJ
426 426
427 427 Objects that are always allowed to be unused
428 428 dependencies.
429 429
430 430
431 431 UNUSED_RPATH
432 432
433 433 Objects that are allowed to have unused runpath
434 434 directories.
435 435
436 436
437 437 ALTERNATIVE DEPENDENCY MAPPING
438 438 check_rtime was primarily designed to process a nightly builds $ROOT
439 439 hierarchy. It is often the case that objects within this hierarchy must
440 440 bind to dependencies within the same hierarchy to satisfy their
441 441 requirements.
442 442
443 443 To achieve this, check_rtime uses the shared objects specified with the
444 444 -D or -d options. If neither option is specified, and the $CODEMGR_WS
445 445 and $ROOT environment variables are defined, the proto area for the
446 446 workspace is used. The objects found are used to create runtime
447 447 configuration files via crle(1), that establish the new shared objects
448 448 as alternatives to their underlying system location. check_rtime
449 449 passes these configuration files as LD_CONFIG environment variable
450 450 settings to ldd(1) using its -e option.
451 451
452 452 The effect of these configuration files is that the execution of an
453 453 object under ldd(1) will bind to the dependencies defined as
454 454 alternatives. Simply put, an object inspected in the proto area will
455 455 bind to its dependencies found in the proto area. Dependencies that
456 456 have no alternative mapping will continue to bind to the underlying
457 457 system.
458 458
459 459 ENVIRONMENT VARIABLES
460 460 When the -D or -d option isn't in use, check_rtime uses the following
461 461 environment variables to establish an alternative dependency mapping:
462 462
463 463 CODEMGR_WS
464 464 The root of your workspace, which is the directory containing
465 465 Codemgr_wsdata. Existence of this environment variable indicates
466 466 that $ROOT should be investigated.
467 467
468 468 ROOT
469 469 Root of the proto area of your workspace. Any shared objects under
470 470 this directory will be used to establish an alternative dependency
471 471 mapping.
472 472
473 473 If ldd(1) supports the -U option, it will be used to determine any
474 474 unreferenced dependencies. Otherwise ldd(1) uses the older -u option
475 475 which only detects unused references. If the following environment
476 476 variable exists, and indicates an earlier release than 5.10 then ldd(1)
477 477 also falls back to using the -u option.
478 478
479 479 RELEASE
480 480 The release version number of the environment being built.
481 481
482 482 ERROR CONDITIONS
483 483 Inspection of an object with ldd(1) assumes it is compatible with the
484 484 machine on which check_rtime is being run. Incompatible objects such
485 485 as a 64-bit object encountered on a 32-bit system, or an i386 object
|
↓ open down ↓ |
195 lines elided |
↑ open up ↑ |
486 486 encountered on a sparc system, can not be fully inspected. These
487 487 objects are displayed as:
488 488
489 489 foo: has wrong class or data encoding
490 490
491 491 FILES
492 492 $CODEMGR_WS/exception_list/check_rtime
493 493 /opt/onbld/etc/exception_list/check_rtime
494 494
495 495 SEE ALSO
496 - crle(1), elfdump(1), find_elf(1), ldd(1), ld.so.1(1), mcs(1).
496 + crle(1), elfdump(1), find_elf(1ONBLD), ldd(1), ld.so.1(1), mcs(1).
497 497
498 498
499 499
500 - 09 March 2010 check_rtime(1)
500 + 09 March 2010 check_rtime(1ONBLD)
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX