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