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