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