Print this page
XXXX check_rtime should be able to forbid libraries
XXXX check_rtime needs to learn libnsl is safe now
XXXX check_rtime could use MACH() more thoroughly
XXXX check_rtime exceptions could be tidied up.


   2 .\"
   3 .\" CDDL HEADER START
   4 .\"
   5 .\" The contents of this file are subject to the terms of the
   6 .\" Common Development and Distribution License (the "License").
   7 .\" You may not use this file except in compliance with the License.
   8 .\"
   9 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  10 .\" or http://www.opensolaris.org/os/licensing.
  11 .\" See the License for the specific language governing permissions
  12 .\" and limitations under the License.
  13 .\"
  14 .\" When distributing Covered Code, include this CDDL HEADER in each
  15 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  16 .\" If applicable, add the following below this CDDL HEADER, with the
  17 .\" fields enclosed by brackets "[]" replaced with your own identifying
  18 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  19 .\"
  20 .\" CDDL HEADER END
  21 .\"
  22 .TH CHECK_RTIME 1ONBLD "Mar 09, 2010"
  23 .SH NAME
  24 .I check_rtime
  25 \- check ELF runtime attributes
  26 .SH SYNOPSIS
  27 \fBcheck_rtime [-imosv] [-D depfile | -d depdir] [-E errfile] [-e exfile] [-f listfile] [-I infofile] [-w outdir] file | dir, ...\fP
  28 .SH DESCRIPTION
  29 .LP
  30 .I check_rtime









  31 attempts to check a number of ELF runtime attributes
  32 for consistency with common build rules.
  33 These checks involve running \fBldd(1)\fP and
  34 \fBelfdump(1)\fP against a family of dynamic objects.
  35 A dynamic object can be defined explicitly as a \fIfile\fP
  36 or multiple dynamic objects can be located under the directory \fIdir\fP.
  37 .LP
  38 .I check_rtime
  39 is typically called from \fBnightly(1ONBLD)\fP when the \fB-r\fP
  40 option is in effect. In this case the dynamic objects under
  41 the associated \fIproto\fP area (\fB$ROOT\fP) are checked.
  42 .I check_rtime












  43 can also be run standalone against any set of dynamic objects.
  44 .LP
  45 .I check_rtime
  46 uses \fBldd(1)\fP to verify dependencies. This implies that
  47 by default any object inspected will bind to its dependencies
  48 as they are found in the \fBunderlying\fP system.  Use of the \fB-D\fP, \fB-d\fP






  49 option, or the existence of the environment variables
  50 \fB$CODEMGR_WS/$ROOT\fP instruct
  51 .I check_rtime



  52 to establish an alternative dependency mapping using
  53 runtime configuration files generated with \fBcrle(1)\fP.
  54 .LP
  55 .I check_rtime
  56 uses \fBldd(1)\fP to completely relocate any dynamic
  57 object and thus detect missing dependencies, unsatisfied
  58 symbol relocations, unused and unreferenced dependencies. These checks
  59 are carried out for the following reasons:
  60 .TP 4
  61 \(bu



  62 An object that cannot find its dependencies may fail to load
  63 at runtime.  This error condition often goes unnoticed
  64 because the existing use of the object is as a dependency itself,
  65 and the objects' dependencies are already satisfied by the
  66 caller.  However, if the object itself is unable to satisfy its
  67 dependencies, its use in new environments may be compromised.
  68 .sp
  69 A missing or erroneous \fBrunpath\fP is the typical reason why
  70 an object can not locate its dependencies.  Use of the link-editors
  71 \fB-zdefs\fP option when building a shared object ensures required
  72 dependencies are established.  This flag is inherited from
  73 \fB$(DYNFLAGS)\fP in \fIlib/Makefile.lib\fP. Missing dependencies
  74 are displayed as:
  75 .sp
  76 .RS 6
  77 foo: bar.so.1 => (file not found)  <no -zdefs?>
  78 .RE
  79 .TP
  80 \(bu




  81 Unsatisfied symbol relocations indicate that some thread of
  82 execution through the object will fail when it is unable to
  83 locate a referenced symbol.
  84 .sp
  85 A missing, or mismatched version of a dependency is the typical
  86 reason for unsatisfied symbol relocations (see missing dependency
  87 discussion above). Unsatisfied symbol relocations are displayed as:
  88 .sp
  89 .RS 6
  90 foo: symbol not found: bar  <no -zdefs?>
  91 .RE
  92 .RS 4
  93 .sp
  94 Note: Shared objects can make reference to symbol definitions
  95 that are expected to be defined by the caller. To indicate that
  96 such symbols are not undefined in the usual sense, you must
  97 specify these symbols in a \fImapfile\fP, using the \fBEXTERN\fP
  98 or \fBPARENT\fP symbol attribute. Without these symbol attributes,
  99 \fBldd(1)\fP is unable to determine the symbols special nature, and
 100 .I check_rtime







 101 will report these symbols as undefined.
 102 .RE
 103 .TP
 104 \(bu
 105 Unused dependencies are wasteful at runtime, as they take time to
 106 load and relocate, but will not be used by the calling object.  They
 107 also result in unnecessary processing at link-edit time.
 108 .sp
 109 Dependency lists (typically defined via \fB$(LDLIBS)\fP)
 110 that have been yanked-and-put
 111 between \fIMakefiles\fP without verifying their need, are a typical
 112 reason why unused dependencies exist.  Unused dependencies are
 113 displayed as:
 114 .sp
 115 .RS 6
 116 foo: unused object=bar.so.1  <remove lib or -zignore?>
 117 .RE
 118 .TP
 119 \(bu
 120 Unreferenced dependencies are also wasteful at runtime, although not
 121 to the extent of unused dependencies.  They also result in unnecessary
 122 processing at link-edit time.
 123 .sp
 124 Unreferenced dependency removal guards against a dependency becoming
 125 unused when combined with
 126 different objects, or as the other object dependencies evolve.
 127 Unreferenced dependencies are displayed as:
 128 .sp
 129 .RS 6
 130 foo: unreferenced object=bar.so.1;  \\
 131 .br
 132     unused dependency of libfoo.so.1  \\
 133 .br
 134     <remove lib or -zignore?>
 135 .RE
 136 .RS 4
 137 .sp
 138 See also the section ENVIRONMENT VARIABLES.
 139 .RE
 140 .TP
 141 \(bu
 142 Unused search paths are wasteful at runtime.
 143 Unused search paths are displayed as:
 144 .sp
 145 .RS 6
 146 foo: unused search path=/usr/foo/lib  \\
 147 .br
 148     (RUNPATH/RPATH from file libfoo.so.1)  \\
 149 .br
 150     <remove search path?>
 151 .RE
 152 .LP
 153 .I check_rtime
 154 uses \fBelfdump(1)\fP to look for a concatenated relocation
 155 section in shared objects, the existence of text relocations,
 156 whether debugging or symbol table information exists, whether
 157 applications have a non-executable stack defined, duplicate
 158 entries in the symbol sorting sections, and for direct bindings.


 159 These checks are carried out for the following reasons:
 160 .TP 4
 161 \(bu
 162 A concatenated relocation section (\fI.SUNW_reloc\fP)
 163 provides optimal symbol table
 164 access at runtime, and thus reduces the overhead of relocating
 165 the shared object.  In past releases, the link-edit of a dynamic object with
 166 the \fB-z combreloc\fP option was required to generate a combined
 167 relocation section.  However, with the integration of 6642769, this section
 168 combination is a default behavior of the link-editor.
 169 .sp
 170 In past releases, not inheriting \fB$(DYNFLAGS)\fP from
 171 \fIlib/Makefile.lib\fP was the typical reason for not having a
 172 concatenated relocation section. The misguided use of the
 173 \fB-z nocombreloc\fP option will also prevent the creation of a
 174 concatenated relocation section. A missing concatenated relocation section
 175 is displayed as:
 176 .sp
 177 .RS 6
 178 foo: .SUNW_reloc section missing  <no -zcombreloc?>
 179 .RE
 180 .TP
 181 \(bu
 182 Text relocations result in impure text segments.  As text segments
 183 are typically read-only, they can be shared between numerous processes.
 184 If they must be updated as part of the relocation then the updated
 185 pages become unsharable and swap space must be allocated to back
 186 these pages.  These events consume unnecessary system resources and
 187 reduce overall system performance.
 188 .sp
 189 Not inheriting the \fB$(PICS)\fP
 190 rules from \fIlib/Makefile.lib\fP is the typical reason for having
 191 non-pic code in shared objects.  Text relocations are displayed as:
 192 .sp
 193 .RS 6
 194 foo: TEXTREL .dynamic tag  <no -Kpic?>
 195 .RE
 196 .TP
 197 \(bu
 198 Debugging information is unnecessary in released objects.  Although
 199 extensive when compiled \fB-g\fP, small quantities of debugging
 200 information are stored in \fI.stabs\fP sections under normal
 201 compilations.  This debugging information is geared towards aiding
 202 debuggers locate relocatable objects associated with the dynamic
 203 objects being debugged.  As relocatable objects aren't made available
 204 as part of a software release this information has no use.
 205 .sp
 206 Not inheriting the correct \fB$(LDFLAGS)\fP from \fIcmd/Makefile.cmd\fP
 207 (which asserts \fP-s\fP), or \fB$(POST_PROCESS_SO)\fP (which asserts
 208 \fIstrip -x\fP) are typical reasons for not removing debugging
 209 information.  Note, removal of debugging information is only enabled
 210 for release builds. The existence of debugging information is displayed as:
 211 .sp
 212 .RS 6












 213 foo: debugging sections should be deleted  \\
 214 .br
 215     <no strip -x?>
 216 .RE
 217 .TP
 218 \(bu
 219 All objects should retain their full \fI.symtab\fP symbol table.

 220 Although this consumes disk space, it provides for more extensive stack
 221 tracing when debugging user applications.
 222 .sp
 223 Hard coding a \fI-s\fP flag with \fB$(LDFLAGS)\fP or
 224 \fB$(DYNFLAGS)\fP is the typical
 225 reason for symbol tables being removed.



 226 Objects that do not contain a symbol table are displayed as:
 227 .sp
 228 .RS 6
 229 foo.so.1: symbol table should not be stripped  \\
 230 .br
 231     <remove -s?>
 232 .RE
 233 .TP
 234 \(bu
 235 Applications should have a non-executable stack defined to make
 236 them less vulnerable to buffer overflow attacks.
 237 .sp
 238 Not inheriting the \fB$(LDFLAGS)\fP macro in \fIcmd/Makefile.cmd\fP



 239 is the typical reason for not having a non-executable stack definition.
 240 Applications without this definition are displayed as:
 241 .sp
 242 .RS 6
 243 foo: application requires non-executable stack \\
 244 .br
 245 .nf
 246         <no -Mmapfile_noexstk?>
 247 .fi
 248 .RE
 249 .sp
 250 .TP
 251 \(bu
 252 x86 applications should have a non-executable data segment defined to make
 253 them less vulnerable to buffer overflow attacks.
 254 .sp
 255 Not inheriting the \fB$(LDFLAGS)\fP macro in \fIcmd/Makefile.cmd\fP



 256 is the typical reason for not having a non-executable data definition.
 257 Applications without this definition are displayed as:
 258 .sp
 259 .RS 6
 260 foo: application requires non-executable data \\
 261 .br
 262 .nf
 263         <no -Mmapfile_noexdata?>
 264 .fi
 265 .RE
 266 .sp
 267 .TP
 268 \(bu
 269 Solaris ELF files contain symbol sort sections used by DTrace to
 270 map addresses in memory to the related function or variable symbols. There
 271 are two such sections, \fI.SUNW_dynsymsort\fP for
 272 regular symbols, and \fI.SUNW_dyntlssort\fP for thread-local
 273 symbols. To ensure that the best names are shown for each
 274 such address, and that the same name is given across Solaris releases,
 275 .I check_rtime



 276 enforces the rule that only one symbol can appear in the sort sections for
 277 any given address.
 278 There are two common ways in which multiple symbols
 279 or a given address occur in the ON distribution. The first is from
 280 code written in assembly language. The second is as a
 281 result of using \fB#pragma weak\fP in C to create weak symbols. The
 282 best solution to this
 283 situation is to modify the code to avoid symbol aliasing. Alternatively,
 284 the \fBNODYNSORT\fP mapfile attribute can be used to eliminate the unwanted
 285 symbol.
 286 .sp



 287 Duplicate entries in a symbol sort section are
 288 displayed in one of the following ways, depending on
 289 whether the section is for regular or thread-local symbols:
 290 .sp
 291 .RS 6
 292 foo: .SUNW_dynsymsort: duplicate ADDRESS: sym1, sym2
 293 .br
 294 foo: .SUNW_dyntlssort: duplicate OFFSET: sym1, sym2
 295 .RE
 296 .sp
 297 .TP
 298 \(bu
 299 \fBOSNet\fP dynamic ELF objects are expected to employ direct bindings whenever
 300 feasible.  This runtime binding technique helps to avoid accidental
 301 interposition problems, and provides a more optimal
 302 runtime symbol search model.
 303 .sp
 304 Not inheriting the correct \fB$(LDFLAGS)\fP from \fIcmd/Makefile.cmd\fP,
 305 or the correct \fB$(DYNFLAGS)\fP from \fIlib/Makefile.lib\fP, are the
 306 typical reasons for not enabling direct bindings. Dynamic objects that
 307 do not contain direct binding information are displayed as:
 308 .sp
 309 .RS 6



 310 foo: object has no direct bindings \\
 311 .br
 312 .nf
 313         <no -B direct or -z direct?>
 314 .fi
 315 .RE
 316 
 317 .sp
 318 .LP
 319 .I check_rtime also
 320 uses \fBelfdump(1)\fP
 321 to display useful dynamic entry information under the \fB-i\fP option.


 322 This doesn't necessarily indicate an error condition, but
 323 provides information that is often useful for gatekeepers to track
 324 changes in a release.  Presently the information listed is:
 325 .TP
 326 \(bu
 327 Runpaths are printed for any dynamic object.  This is a historic
 328 sanity check to insure compiler supplied runpaths (typically from \fBCC\fP)
 329 are not recorded in any objects.  Runpaths are displayed as:
 330 .sp
 331 .RS 6
 332 foo: RPATH=/usr/bar/lib
 333 .RE
 334 .TP
 335 \(bu

 336 Needed dependencies are printed for any dynamic object.
 337 In the freeware world this often helps the introducer of a new
 338 shared object discover that an existing binary has become its
 339 consumer, and thus that binaries package dependencies may require updating.
 340 Dependencies are printed as:
 341 .sp
 342 .RS 6
 343 foo: NEEDED=bar.so.1
 344 .RE
 345 .sp
 346 .LP
 347 .I check_rtime
 348 uses \fBmcs(1)\fP to inspect an object's \fI.comment\fP section.









 349 During development, this section contains numerous file identifiers
 350 marked with the tag "\fB@(#)\fP".  For release builds these sections
 351 are deleted and rewritten under control of the \fB$(POST_PROCESS)\fP
 352 macro to produce a common release identifier.  This identifier
 353 typically consists of three lines including a single comment starting
 354 with the string "\fB@(#) SunOS\fP".  If this common identifier isn't
 355 found the following diagnostic is generated:
 356 .sp
 357 .RS 6
 358 foo: non-conforming mcs(1) comment  <no $(POST_PROCESS)?>
 359 .RE
 360 .sp
 361 .LP
 362 .I check_rtime
 363 uses \fBpvs(1)\fP to display version definitions under the \fB-v\fP option.





 364 Each symbol defined by the object is shown along with the version it belongs to.
 365 Changes to the symbols defined by an object, or the versions they belong to,
 366 do not necessarily indicate an error condition, but
 367 provides information that is often useful for gatekeepers to track
 368 changes in a release.
 369 .sp
 370 .SH OPTIONS
 371 .LP
 372 The following options are supported:
 373 .TP 4
 374 .B \-D depfile
 375 Use \fIdepfile\fP to generate an alternative dependency mapping.
 376 \fIdepfile\fP must be created by '\fBfind_elf -r\fP'.
 377 The \fB-D\fP and \fB-d\fP options are mutually exclusive.
 378 .TP
 379 .B \-d depdir
 380 Use \fIdepdir\fP to generate an alternative dependency mapping.
 381 \fBfind_elf(1ONBLD)\fP is used to locate the ELF sharable objects for
 382 which alternative mappings are required. The \fB-D\fP and \fB-d\fP options
 383 are mutually exclusive.
 384 .TP 4
 385 .B \-E errfile
 386 Direct error messages for the analyzed objects to \fIerrfile\fP instead
 387 of stdout.
 388 .TP 4
 389 .B \-e exfile













 390 An exception file is used to exclude objects from
 391 the usual rules. See EXCEPTION FILE FORMAT.
 392 .TP
 393 .B \-f listfile

 394 Normally,
 395 .I interface_check
 396 runs
 397 .I find_elf
 398 to locate the ELF objects to analyze. The \fB-f\fP option can be
 399 used to instead provide a file containing the list of objects to
 400 analyze, in the format produced by '\fBfind_elf -r\fP'.
 401 .TP
 402 .B -I infofile
 403 Direct informational messages (\fB-i\fP, and \fB-v\fP options) for the
 404 analyzed objects to \fIinfofile\fP instead of stdout.
 405 .TP
 406 .B \-i
 407 Provide dynamic entry information.  Presently only dependencies and
 408 runpaths are printed.
 409 .TP
 410 .B \-m
 411 Enable \fBmcs(1)\fP checking.
 412 .TP
 413 .B \-o






 414 Produce a one-line output for each condition discovered, prefixed
 415 by the objects name.  This output style is more terse, but is
 416 more appropriate for sorting and diffing with previous build results.
 417 .TP
 418 .B \-s
 419 Determine whether \fI.stabs\fP sections exist.
 420 .TP
 421 .B \-v
 422 Provide version definition information. Each symbol defined by the object
 423 is printed along with the version it is assigned to.
 424 .TP
 425 .B -w outdir
 426 Interpret the paths of all input and output files relative to \fIoutdir\fP.
 427 .SH EXCEPTION FILE FORMAT



 428 Exceptions to the rules enforced by
 429 .I check_rtime
 430 are specified using an exception file. The \fB-e\fP option is used to
 431 specify an explicit exception file. Otherwise, if used in an activated
 432 workspace, the default exception file is
 433 $CODEMGR_WS/exception_list/check_rtime
 434 if that file exists. If not used in an activated workspace, or if
 435 $CODEMGR_WS/exception_list/check_rtime does not exist,
 436 .I check_rtime




 437 will use
 438 .I /opt/onbld/etc/exception_list/check_rtime
 439 as a fallback default exception file.
 440 .P
 441 To run
 442 .I check_rtime
 443 without applying exceptions, specify \fB-e\fP with a value of /dev/null.
 444 .P
 445 A '#' character at the beginning of a line, or at any point in
 446 a line when preceded by whitespace, introduces a comment. Empty lines,
 447 and lines containing only comments, are ignored by
 448 .I check_rtime.
 449 Exceptions are specified as space separated keyword, and \fBperl(1)\fP






 450 regular expression:
 451 .sp
 452 .in +4
 453 .nf
 454 keyword  perl-regex
 455 .fi
 456 .in -4
 457 .sp
 458 Since whitespace is used as a separator, the regular
 459 expression cannot itself contain whitespace. Use of the \\s character
 460 class to represent whitespace within the regular expression is recommended.




 461 Before the perl regular expression is used, constructs of the form
 462 MACH(dir) are expanded into a regular expression that matches the directory
 463 given, as well as any 64-bit architecture subdirectory that
 464 might be present (i.e. amd64, sparcv9). For instance, MACH(lib) will
 465 match any of the following:
 466 .sp
 467 .in +4
 468 .nf
 469 lib
 470 lib/amd64
 471 lib/sparcv9
 472 .fi
 473 .in -4
 474 .sp
 475 The exceptions understood by
 476 .I check_rtime
 477 are:
 478 .sp
 479 .ne 2
 480 .na
 481 \fBEXEC_DATA\fR
 482 .ad
 483 .RS 17n
 484 .sp
 485 Executables that are not required to have non-executable writable
 486 data segments
 487 .RE
 488 
 489 .sp
 490 .ne 2
 491 .na
 492 \fBEXEC_STACK\fR
 493 .ad
 494 .RS 17n
 495 .sp
 496 Executables that are not required to have a non-executable stack
 497 .RE
 498 
 499 .sp
 500 .ne 2
 501 .na
 502 \fBNOCRLEALT\fR
 503 .ad
 504 .RS 17n
 505 .sp
 506 Objects that should be skipped when building the alternative dependency
 507 mapping via the \fB-d\fP option.
 508 .RE
 509 
 510 .sp
 511 .ne 2
 512 .na
 513 \fBNODIRECT\fR
 514 .ad
 515 .RS 17n
 516 .sp
 517 Directories and files that are allowed to have no direct bound symbols.
 518 .RE
 519 
 520 .sp
 521 .ne 2
 522 .na
 523 \fBNOSYMSORT\fR
 524 .ad
 525 .RS 17n
 526 .sp
 527 Files for which we skip checking of duplicate addresses in the
 528 symbol sort sections.
 529 .RE
 530 
 531 .sp
 532 .ne 2
 533 .na
 534 \fBOLDDEP\fR
 535 .ad
 536 .RS 17n
 537 .sp
 538 Objects that used to contain system functionality that has since
 539 migrated to libc. We preserve these libraries as pure filters for
 540 backward compatibility but nothing needs to link to them.
 541 .RE
 542 
 543 .sp
 544 .ne 2
 545 .na
 546 \fBSKIP\fR
 547 .ad
 548 .RS 17n
 549 .sp
 550 Directories and/or individual objects to skip. Note that SKIP should be
 551 a last resort, used only when one of the other exceptions will not suffice.
 552 .RE
 553 
 554 .sp
 555 .ne 2
 556 .na
 557 \fBSTAB\fR
 558 .ad
 559 .RS 17n
 560 .sp
 561 Objects that are allowed to contain debugging information (stabs).
 562 .RE
 563 
 564 .sp
 565 .ne 2
 566 .na
 567 \fBTEXTREL\fR
 568 .ad
 569 .RS 17n
 570 .sp
 571 Objects for which we allow relocations to the text segment.
 572 .RE
 573 
 574 .sp
 575 .ne 2
 576 .na
 577 \fBUNDEF_OBJ\fR
 578 .ad
 579 .RS 17n
 580 .sp
 581 Objects that are allowed to be unreferenced.
 582 .RE
 583 
 584 .sp
 585 .ne 2
 586 .na
 587 \fBUNDEF_REF\fR
 588 .ad
 589 .RS 17n
 590 .sp
 591 Objects that are allowed undefined references.
 592 .RE
 593 
 594 .sp
 595 .ne 2
 596 .na
 597 \fBUNUSED_DEPS\fR
 598 .ad
 599 .RS 17n
 600 .sp
 601 Objects that are allowed to have unused dependencies.
 602 .RE
 603 
 604 .sp
 605 .ne 2
 606 .na
 607 \fBUNUSED_OBJ\fR
 608 .ad
 609 .RS 17n
 610 .sp
 611 Objects that are always allowed to be unused dependencies.
 612 .RE
 613 
 614 .sp
 615 .ne 2
 616 .na
 617 \fBUNUSED_RPATH\fR
 618 .ad
 619 .RS 17n
 620 .sp
 621 Objects that are allowed to have unused runpath directories.
 622 .RE
 623 
 624 .SH ALTERNATIVE DEPENDENCY MAPPING
 625 .I check_rtime
 626 was primarily designed to process a nightly builds \fB$ROOT\fP
 627 hierarchy. It is often the case that objects within this hierarchy
 628 must bind to dependencies within the same hierarchy to satisfy
 629 their requirements.
 630 .LP




 631 To achieve this,
 632 .I check_rtime
 633 uses the shared objects specified with the \fB-D\fP or \fB-d\fP options.
 634 If neither option is specified, and the \fB$CODEMGR_WS\fP and \fB$ROOT\fP
 635 environment variables are defined, the proto area for the workspace
 636 is used. The objects found are used
 637 to create runtime configuration files via \fBcrle(1)\fP, that establish
 638 the new shared objects as alternatives to their underlying system location.
 639 .I check_rtime
 640 passes these configuration files as \fBLD_CONFIG\fP environment
 641 variable settings to \fBldd(1)\fP using its \fB-e\fP option.
 642 .LP














 643 The effect of these configuration files is that the execution of an
 644 object under \fBldd(1)\fP will bind to the dependencies defined as
 645 alternatives.  Simply put, an object inspected in the \fIproto\fP
 646 area will bind to its dependencies found in the \fIproto\fP area.
 647 Dependencies that have no alternative mapping will continue to
 648 bind to the underlying system.
 649 .SH ENVIRONMENT VARIABLES
 650 .LP
 651 When the \fB-D\fP or \fB-d\fP option isn't in use,
 652 .I check_rtime








 653 uses the following environment variables to
 654 establish an alternative dependency mapping:
 655 .LP
 656 .B CODEMGR_WS
 657 .RS 4
 658 The root of your workspace, which is the directory
 659 containing \fICodemgr_wsdata\fP. Existence of this environment variable
 660 indicates that \fB$ROOT\fP should be investigated.
 661 .RE
 662 .LP
 663 .B ROOT
 664 .RS 4
 665 Root of the \fIproto\fP area of your workspace. Any shared objects
 666 under this directory will be used to establish an alternative dependency
 667 mapping.
 668 .RE
 669 .sp
 670 If \fBldd(1)\fP supports the \fB-U\fP option, it will be used to determine
 671 any unreferenced dependencies.  Otherwise \fBldd(1)\fP uses the older
 672 \fB-u\fP option which only detects unused references.  If the following
 673 environment variable exists, and indicates an earlier release than \fB5.10\fP
 674 then \fBldd(1)\fP also falls back to using the \fB-u\fP option.
 675 .LP
 676 .B RELEASE
 677 .RS 4











 678 The release version number of the environment being built.
 679 .RE
 680 .SH ERROR CONDITIONS
 681 .LP
 682 Inspection of an object with \fBldd(1)\fP assumes it is compatible
 683 with the machine on which
 684 .I check_rtime
 685 is being run.  Incompatible objects such as a 64-bit object encountered on
 686 a 32-bit system, or an i386 object encountered on a sparc system,
 687 can not be fully inspected.  These objects are displayed as:
 688 .sp
 689 .RS 4
 690 foo: has wrong class or data encoding
 691 .RE
 692 .SH FILES
 693 .LP
 694 .RS 5
 695 $CODEMGR_WS/exception_list/check_rtime
 696 /opt/onbld/etc/exception_list/check_rtime
 697 .SH SEE ALSO
 698 .B crle(1),
 699 .B elfdump(1),
 700 .B find_elf(1ONBLD),
 701 .B ldd(1),
 702 .B ld.so.1(1),
 703 .B mcs(1).


   2 .\"
   3 .\" CDDL HEADER START
   4 .\"
   5 .\" The contents of this file are subject to the terms of the
   6 .\" Common Development and Distribution License (the "License").
   7 .\" You may not use this file except in compliance with the License.
   8 .\"
   9 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  10 .\" or http://www.opensolaris.org/os/licensing.
  11 .\" See the License for the specific language governing permissions
  12 .\" and limitations under the License.
  13 .\"
  14 .\" When distributing Covered Code, include this CDDL HEADER in each
  15 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  16 .\" If applicable, add the following below this CDDL HEADER, with the
  17 .\" fields enclosed by brackets "[]" replaced with your own identifying
  18 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  19 .\"
  20 .\" CDDL HEADER END
  21 .\"
  22 .Dd February 19, 2018
  23 .Dt CHECK_RTIME 1ONBLD
  24 .Os
  25 .Sh NAME
  26 .Nm check_rtime
  27 .Nd check ELF runtime attributes
  28 .Sh SYNOPSIS
  29 .Nm check_rtime
  30 .Op Fl imosv
  31 .Op Fl D Ar depfile | Fl d depdir
  32 .Op Fl E Ar errfile
  33 .Op Fl e Ar exfile
  34 .Op Fl f Ar listfile
  35 .Op Fl I Ar infofile
  36 .Op Fl w Ar outdir
  37 .Ar file | dir ...
  38 .Sh DESCRIPTION
  39 .Nm check_rtime
  40 attempts to check a number of ELF runtime attributes
  41 for consistency with common build rules.
  42 These checks involve running
  43 .Xr ldd 1
  44 and
  45 .Xr elfdump 1
  46 against a family of dynamic objects.
  47 A dynamic object can be defined explicitly as a
  48 .Ar file
  49 or multiple dynamic objects can be located under the directory
  50 .Ar dir .
  51 .Pp
  52 .Nm check_rtime
  53 is typically called from
  54 .Xr nightly 1ONBLD
  55 when the
  56 .Fl r
  57 option is in effect.
  58 In this case the dynamic objects under
  59 the associated
  60 .Em proto area
  61 .Pq Ev $ROOT
  62 are checked.
  63 .Nm check_rtime
  64 can also be run standalone against any set of dynamic objects.
  65 .Pp
  66 .Nm check_rtime
  67 uses
  68 .Xr  ldd 1
  69 to verify dependencies.
  70 This implies that by default any object inspected will bind to its dependencies
  71 as they are found in the
  72 .Em underlying system .
  73 Use of the
  74 .Fl D ,
  75 .Fl d
  76 option, or the existence of the environment variables
  77 .Ev $CODEMGR_WS
  78 or
  79 .Ev $ROOT
  80 instruct
  81 .Nm check_rtime
  82 to establish an alternative dependency mapping using
  83 runtime configuration files generated with
  84 .Xr crle 1 .
  85 .Pp
  86 .Nm check_rtime
  87 uses
  88 .Xr ldd 1
  89 to completely relocate any dynamic object and thus detect missing
  90 dependencies, unsatisfied symbol relocations, unused and unreferenced
  91 dependencies.
  92 These checks are carried out for the following reasons:
  93 .Bl -bullet
  94 .It
  95 An object that cannot find its dependencies may fail to load
  96 at runtime.
  97 This error condition often goes unnoticed because the existing use of the
  98 object is as a dependency itself, and the objects' dependencies are already
  99 satisfied by the caller.
 100 However, if the object itself is unable to satisfy its dependencies, its use
 101 in new environments may be compromised.
 102 .Pp
 103 A missing or erroneous
 104 .Em runpath
 105 is the typical reason why an object can not locate its dependencies.
 106 Use of the link-editors
 107 .Fl zdefs
 108 option when building a shared object ensures required dependencies are
 109 established.
 110 This flag is inherited from
 111 .Dv $(DYNFLAGS)
 112 in
 113 .Pa lib/Makefile.lib .
 114 Missing dependencies are displayed as:
 115 .Pp
 116 .Dl foo: bar.so.1 => (file not found)  <no -zdefs?>
 117 .It
 118 Unsatisfied symbol relocations indicate that some thread of
 119 execution through the object will fail when it is unable to
 120 locate a referenced symbol.
 121 .Pp
 122 A missing, or mismatched version of a dependency is the typical
 123 reason for unsatisfied symbol relocations (see missing dependency
 124 discussion above). Unsatisfied symbol relocations are displayed as:
 125 .Pp
 126 .Dl foo: symbol not found: bar  <no -zdefs?>
 127 .Pp



 128 Note: Shared objects can make reference to symbol definitions
 129 that are expected to be defined by the caller.
 130 To indicate that such symbols are not undefined in the usual sense, you must
 131 specify these symbols in a
 132 .Em mapfile ,
 133 using the
 134 .Va EXTERN
 135 or
 136 .Va PARENT
 137 symbol attributes.
 138 Without these symbol attributes,
 139 .Xr ldd 1
 140 is unable to determine the symbols special nature, and
 141 .Nm check_rtime
 142 will report these symbols as undefined.
 143 .It


 144 Unused dependencies are wasteful at runtime, as they take time to
 145 load and relocate, but will not be used by the calling object.
 146 They also result in unnecessary processing at link-edit time.
 147 .Pp
 148 Dependency lists (typically defined via
 149 .Dv $(LDLIBS) )
 150 that have been copy and pasted
 151 between
 152 .Pa Makefiles
 153 without verifying their need, are a typicalreason why unused dependencies
 154 exist.
 155 Unused dependencies are displayed as:
 156 .Pp
 157 .Dl foo: unused object=bar.so.1  <remove lib or -zignore?>
 158 .It
 159 Unreferenced dependencies are also wasteful at runtime, although not
 160 to the extent of unused dependencies.
 161 They also result in unnecessary processing at link-edit time.
 162 .Pp
 163 Unreferenced dependency removal guards against a dependency becoming
 164 unused when combined with
 165 different objects, or as the other object dependencies evolve.
 166 Unreferenced dependencies are displayed as:
 167 .Bd -literal

 168 foo: unreferenced object=bar.so.1;  \\

 169     unused dependency of libfoo.so.1  \\

 170     <remove lib or -zignore?>
 171 .Ed
 172 .Pp
 173 See also the section
 174 .Sx ENVIRONMENT VARIABLES .
 175 .It


 176 Unused search paths are wasteful at runtime.
 177 Unused search paths are displayed as:
 178 .Bd -literal

 179 foo: unused search path=/usr/foo/lib  \\

 180     (RUNPATH/RPATH from file libfoo.so.1)  \\

 181     <remove search path?>
 182 .Ed
 183 .El
 184 .Pp
 185 .Nm check_rtime
 186 uses
 187 .Xr elfdump 1
 188 to look for a concatenated relocation section in shared objects, the existence
 189 of text relocations, whether debugging or symbol table information exists,
 190 whether applications have a non-executable stack defined, duplicate entries in
 191 the symbol sorting sections, and for direct bindings.
 192 These checks are carried out for the following reasons:
 193 .Bl -bullet
 194 .It
 195 A concatenated relocation section 
 196 .Pq Em .SUNW_reloc
 197 provides optimal symbol table access at runtime, and thus reduces the overhead
 198 of relocating the shared object.
 199 In past releases, the link-edit of a dynamic object with the
 200 .Fl z Ar combreloc
 201 option was required to generate a combined relocation section.
 202 However, with the integration of 6642769, this section combination is a default behavior of
 203 the link-editor.
 204 .Pp
 205 In past releases, not inheriting
 206 .Dv $(DYNFLAGS)
 207 from
 208 .Pa lib/Makefile.lib
 209 was the typical reason for not having a concatenated relocation section.
 210 The misguided use of the
 211 .Fl z Ar nocombreloc
 212 option will also prevent the creation of a concatenated relocation section.
 213 A missing concatenated relocation section is displayed as:
 214 .Pp
 215 .Dl foo: .SUNW_reloc section missing  <no -zcombreloc?>
 216 .It
 217 Text relocations result in impure text segments.
 218 As text segments are typically read-only, they can be shared between numerous
 219 processes.
 220 If they must be updated as part of the relocation then the updated pages
 221 become unsharable and swap space must be allocated to back these pages.
 222 These events consume unnecessary system resources and reduce overall system
 223 performance.
 224 .Pp
 225 Not inheriting the
 226 .Dv $(PICS)
 227 rules from
 228 .Pa lib/Makefile.lib
 229 is the typical reason for having non-pic code in shared objects.
 230 Text relocations are displayed as:
 231 .Pp
 232 .Dl foo: TEXTREL .dynamic tag  <no -Kpic?>
 233 .It
 234 Debugging information is unnecessary in released objects.
 235 Although extensive when compiled
 236 .Fl g ,
 237 small quantities of debugging information are stored in
 238 .Em .stabs
 239 sections under normal compilations.
 240 This debugging information is geared towards aiding debuggers locate
 241 relocatable objects associated with the dynamic objects being debugged.
 242 As relocatable objects aren't made available as part of a software release
 243 this information has no use.
 244 .Pp
 245 Not inheriting the correct
 246 .Dv $(LDFLAGS)
 247 from
 248 .Pa cmd/Makefile.cmd
 249 .Pq which asserts Fl s
 250 or
 251 .Dv $(POST_PROCESS_SO)
 252 .Pq which asserts Ic strip -x
 253 are typical reasons for not removing debugging information.
 254 Note, removal of debugging information is only enabled
 255 for release builds.
 256 The existence of debugging information is displayed as:
 257 .Bd -literal
 258 foo: debugging sections should be deleted  \\

 259     <no strip -x?>
 260 .Ed
 261 .It
 262 All objects should retain their full
 263 .Em .symtab
 264 symbol table.
 265 Although this consumes disk space, it provides for more extensive stack
 266 tracing when debugging user applications.
 267 .Pp
 268 Hard coding a
 269 .Fl s
 270 flag with
 271 .Dv $(LDFLAGS) or
 272 .Dv $(DYNFLAGS)
 273 is the typical reason for symbol tables being removed.
 274 Objects that do not contain a symbol table are displayed as:
 275 .Bd -literal

 276 foo.so.1: symbol table should not be stripped  \\

 277     <remove -s?>
 278 .Ed
 279 .It

 280 Applications should have a non-executable stack defined to make
 281 them less vulnerable to buffer overflow attacks.
 282 .Pp
 283 Not inheriting the
 284 .Dv $(LDFLAGS)
 285 macro in
 286 .Pa cmd/Makefile.cmd
 287 is the typical reason for not having a non-executable stack definition.
 288 Applications without this definition are displayed as:
 289 .Bd -literal

 290 foo: application requires non-executable stack \\


 291         <no -Mmapfile_noexstk?>
 292 .Ed
 293 .It



 294 x86 applications should have a non-executable data segment defined to make
 295 them less vulnerable to buffer overflow attacks.
 296 .Pp
 297 Not inheriting the
 298 .Dv $(LDFLAGS)
 299 macro in
 300 .Pa cmd/Makefile.cmd
 301 is the typical reason for not having a non-executable data definition.
 302 Applications without this definition are displayed as:
 303 .Bd -literal

 304 foo: application requires non-executable data \\


 305         <no -Mmapfile_noexdata?>
 306 .Ed
 307 .It



 308 Solaris ELF files contain symbol sort sections used by DTrace to
 309 map addresses in memory to the related function or variable symbols.
 310 There are two such sections,
 311 .Em .SUNW_dynsymsort
 312 for regular symbols, and
 313 .Em .SUNW_dyntlssort
 314 for thread-local symbols.
 315 To ensure that the best names are shown for each such address, and that the
 316 same name is given across Solaris releases,
 317 .Nm check_rtime
 318 enforces the rule that only one symbol can appear in the sort sections for
 319 any given address.
 320 There are two common ways in which multiple symbols
 321 or a given address occur in the ON distribution.
 322 The first is from code written in assembly language.
 323 The second is as a result of using
 324 .Ic #pragma weak
 325 in C to create weak symbols.
 326 The best solution to this situation is to modify the code to avoid symbol
 327 aliasing.
 328 Alternatively, the
 329 .Va NODYNSORT
 330 mapfile attribute can be used to eliminate the unwanted symbol.
 331 .Pp
 332 Duplicate entries in a symbol sort section are
 333 displayed in one of the following ways, depending on
 334 whether the section is for regular or thread-local symbols:
 335 .Bd -literal

 336 foo: .SUNW_dynsymsort: duplicate ADDRESS: sym1, sym2

 337 foo: .SUNW_dyntlssort: duplicate OFFSET: sym1, sym2
 338 .Ed
 339 .It
 340 illumos dynamic ELF objects are expected to employ direct bindings whenever
 341 feasible.
 342 This runtime binding technique helps to avoid accidental interposition
 343 problems, and provides a more optimal runtime symbol search model.
 344 .Pp
 345 Not inheriting the correct
 346 .Dv $(LDFLAGS) from
 347 .Pa cmd/Makefile.cmd ,
 348 or the correct
 349 .Dv $(DYNFLAGS)
 350 from
 351 .Pa lib/Makefile.lib ,
 352 are the typical reasons for not enabling direct bindings.
 353 Dynamic objects that do not contain direct binding information are displayed
 354 as:
 355 .Bd -literal
 356 foo: object has no direct bindings \\


 357         <no -B direct or -z direct?>
 358 .Ed
 359 .El
 360 .Pp
 361 .Nm check_rtime
 362 also
 363 uses
 364 .Xr elfdump 1
 365 to display useful dynamic entry information under the
 366 .Fl -i
 367 option.
 368 This doesn't necessarily indicate an error condition, but
 369 provides information that is often useful for gatekeepers to track
 370 changes in a release.
 371 Presently the information listed is:
 372 .Bl -bullet
 373 .It
 374 Runpaths are printed for any dynamic object.
 375 This is a historic sanity check to insure compiler supplied runpaths
 376 (typically from
 377 .Nm CC )
 378 are not recorded in any objects.
 379 Runpaths are displayed as:
 380 .Pp
 381 .Dl foo: RPATH=/usr/bar/lib
 382 .It
 383 Needed dependencies are printed for any dynamic object.
 384 In the freeware world this often helps the introducer of a new
 385 shared object discover that an existing binary has become its
 386 consumer, and thus that binaries package dependencies may require updating.
 387 Dependencies are printed as:
 388 .Pp
 389 .Dl foo: NEEDED=bar.so.1
 390 .It
 391 Dependencies may be marked as forbidden
 392 .Pq see Sx EXCEPTION FILE FORMAT 
 393 this allows the build to warn should people use them accidentally.
 394 Forbidden dependencies are printed as:
 395 .Pp
 396 .Dl foo: NEEDED=bar.so.1        <forbidden dependency, missing -nodefaultlibs?>
 397 .El
 398 .Pp
 399 .Nm check_rtime
 400 uses
 401 .Xr mcs 1
 402 to inspect an object's
 403 .Em .comment
 404 section.
 405 During development, this section contains numerous file identifiers
 406 marked with the tag
 407 .Qq @(#) .
 408 For release builds these sections are deleted and rewritten under control of
 409 the
 410 .Dv $(POST_PROCESS)
 411 macro to produce a common release identifier.
 412 This identifier typically consists of three lines including a single comment
 413 starting with the string
 414 .Qq @(#) SunOS .
 415 If this common identifier isn't found the following diagnostic is generated:
 416 .Pp
 417 .Dl foo: non-conforming mcs(1) comment  <no $(POST_PROCESS)?>
 418 .Pp
 419 .Nm check_rtime
 420 uses
 421 .Xr pvs 1
 422 to display version definitions under the
 423 .Fl v
 424 option.
 425 Each symbol defined by the object is shown along with the version it belongs to.
 426 Changes to the symbols defined by an object, or the versions they belong to,
 427 do not necessarily indicate an error condition, but
 428 provides information that is often useful for gatekeepers to track
 429 changes in a release.
 430 .Sh OPTIONS


 431 The following options are supported:
 432 .Bl -tag -width indent
 433 .It Fl D Ar depfile
 434 Use
 435 .Ar depfile
 436 to generate an alternative dependency mapping.
 437 .Ar depfile
 438 must be created by
 439 .Ic find_elf -r .
 440 The
 441 .Fl D
 442 and
 443 .Fl d
 444 options are mutually exclusive.
 445 .It Fl d Ar depfile
 446 Use
 447 .Ar depdir
 448 to generate an alternative dependency mapping.
 449 .Xr find_elf 1ONBLD
 450 is used to locate the ELF sharable objects for which alternative mappings are
 451 required.
 452 The
 453 .Fl D
 454 and
 455 .Fl d
 456 options are mutually exclusive.
 457 .It Fl E Ar errfile
 458 Direct error messages for the analyzed objects to
 459 .Ar errfile
 460 instead of stdout.
 461 .It Fl e Ar exfile
 462 An exception file is used to exclude objects from
 463 the usual rules.
 464 See
 465 .Sx EXCEPTION FILE FORMAT .
 466 .It Fl f Ar listfile
 467 Normally,
 468 .Ic interface_check
 469 runs
 470 .Ic find_elf
 471 to locate the ELF objects to analyze.
 472 The
 473 .Fl f
 474 option can be used to instead provide a file containing the list of objects to
 475 analyze, in the format produced by
 476 .Ic find_elf -r .
 477 .It Fl I Ar infofile
 478 Direct informational messages (
 479 .Fl i ,
 480 and
 481 .Fl v
 482 options) for the analyzed objects to
 483 .Ar infofile
 484 instead of stdout.
 485 .It Fl i
 486 Provide dynamic entry information.
 487 Presently only dependencies and runpaths are printed.
 488 .It Fl m
 489 Enable
 490 .Xr mcs 1
 491 checking.
 492 .It Fl o
 493 Produce a one-line output for each condition discovered, prefixed
 494 by the objects name.
 495 This output style is more terse, but is more appropriate for sorting and
 496 diffing with previous build results.
 497 .It Fl s
 498 Determine whether
 499 .Em .stabs
 500 sections exist.
 501 .It Fl v
 502 Provide version definition information.
 503 Each symbol defined by the object is printed along with the version it is
 504 assigned to.
 505 .It Fl w Ar outdir
 506 Interpret the paths of all input and output files relative to
 507 .Ar outdir .
 508 .El
 509 .Sh EXCEPTION FILE FORMAT
 510 Exceptions to the rules enforced by
 511 .Nm check_rtime
 512 are specified using an exception file.
 513 The
 514 .Fl -e
 515 option is used to specify an explicit exception file.
 516 Otherwise, if used in an activated workspace, the default exception file is
 517 .Pa $CODEMGR_WS/exception_list/check_rtime
 518 if that file exists.
 519 If not used in an activated workspace, or if
 520 .Pa $CODEMGR_WS/exception_list/check_rtime
 521 does not exist,
 522 .Nm check_rtime
 523 will use
 524 .Pa /opt/onbld/etc/exception_list/check_rtime
 525 as a fallback default exception file.
 526 .Pp
 527 To run
 528 .Nm check_rtime
 529 without applying exceptions, specify
 530 .Fl e
 531 with a value of
 532 .Pa /dev/null .
 533 .Pp
 534 A
 535 .Ql #
 536 character at the beginning of a line, or at any point in
 537 a line when preceded by whitespace, introduces a comment.
 538 Empty lines, and lines containing only comments, are ignored by
 539 .Nm check_rtime .
 540 Exceptions are specified as space separated keyword, and
 541 .Xr perl 1
 542 regular expression:
 543 .Pp
 544 .Dl keyword  perl-regex
 545 .Pp




 546 Since whitespace is used as a separator, the regular
 547 expression cannot itself contain whitespace.
 548 Use of the
 549 .Ql \\s
 550 character class to represent whitespace within the regular expression is
 551 recommended.
 552 .Pp
 553 Before the perl regular expression is used, constructs of the form
 554 .Em MACH(dir)
 555 are expanded into a regular expression that matches the directory given, as
 556 well as any 64-bit architecture subdirectory that might be present
 557 (i.e. amd64, sparcv9). For instance,
 558 .Em MACH(lib)
 559 will match any of the following:
 560 .Bl -tag -width indent
 561 .It Pa lib
 562 .It Pa lib/amd64
 563 .It Pa lib/sparcv9
 564 .El
 565 .Pp

 566 The exceptions understood by
 567 .Nm check_rtime
 568 are:
 569 .Bl -tag -width indent
 570 .It EXEC_DATA





 571 Executables that are not required to have non-executable writable
 572 data segments
 573 .It EXEC_STACK








 574 Executables that are not required to have a non-executable stack
 575 .It NOCRLEALT








 576 Objects that should be skipped when building the alternative dependency
 577 mapping via the
 578 .Fl d
 579 option.
 580 .It NODIRECT






 581 Directories and files that are allowed to have no direct bound symbols.
 582 .It NOSYMSORT








 583 Files for which we skip checking of duplicate addresses in the
 584 symbol sort sections.
 585 .It OLDDEP








 586 Objects that used to contain system functionality that has since
 587 migrated to libc.
 588 We preserve these libraries as pure filters for backward compatibility but
 589 nothing needs to link to them.
 590 .It SKIP
 591 Directories and/or individual objects to skip.
 592 Note that SKIP should be a last resort, used only when one of the other
 593 exceptions will not suffice.
 594 .It STAB














 595 Objects that are allowed to contain debugging information (stabs).
 596 .It TEXTREL








 597 Objects for which we allow relocations to the text segment.
 598 .It BUNDEF_OBJ








 599 Objects that are allowed to be unreferenced.
 600 .It UNDEF_REF








 601 Objects that are allowed undefined references.
 602 .It UNUSED_DEPS








 603 Objects that are allowed to have unused dependencies.
 604 .It BUNUSED_OBJ








 605 Objects that are always allowed to be unused dependencies.
 606 .It UNUSED_RPATH








 607 Objects that are allowed to have unused runpath directories.
 608 .It FORBIDDEN
 609 Specifies that dependencies on a given object are forbidden.
 610 .It FORBIDDEN_DEP
 611 Specifies that a given object is permitted a forbidden dependency.
 612 .El
 613 .Sh ALTERNATIVE DEPENDENCY MAPPING
 614 .Nm check_rtime
 615 was primarily designed to process a nightly builds
 616 .Ev $ROOT
 617 hierarchy.
 618 It is often the case that objects within this hierarchy must bind to
 619 dependencies within the same hierarchy to satisfy their requirements.
 620 .Pp
 621 To achieve this,
 622 .Nm check_rtime
 623 uses the shared objects specified with the
 624 .Fl D
 625 or
 626 .Fl d
 627 options.
 628 If neither option is specified, and the
 629 .Ev $CODEMGR_WS
 630 and
 631 .Ev $ROOT
 632 environment variables are defined, the proto area for the workspace is
 633 used.
 634 The objects found are used to create runtime configuration files via
 635 .Xr crle 1 ,
 636 that establish the new shared objects as alternatives to their underlying
 637 system location.
 638 .Nm check_rtime
 639 passes these configuration files as
 640 .Ev LD_CONFIG
 641 environment variable settings to
 642 .Xr ldd 1
 643 using its
 644 .Fl -e
 645 option.
 646 .Pp
 647 The effect of these configuration files is that the execution of an
 648 object under
 649 .Xr ldd 1
 650 will bind to the dependencies defined as alternatives.
 651 Simply put, an object inspected in the
 652 .Pa proto
 653 area will bind to its dependencies found in the
 654 .Pa proto
 655 area.
 656 Dependencies that have no alternative mapping will continue to bind to the
 657 underlying system.
 658 .Sh ENVIRONMENT VARIABLES
 659 When the
 660 .Fl D
 661 or
 662 .Fl d
 663 option isn't in use,
 664 .Nm check_rtime
 665 uses the following environment variables to
 666 establish an alternative dependency mapping:
 667 .Bl -tag -width indent
 668 .It Ev CODEMGR_WS

 669 The root of your workspace, which is the directory
 670 containing
 671 .Pa .git .
 672 Existence of this environment variable indicates that
 673 .Ev $ROOT
 674 should be investigated.
 675 .It Ev ROOT
 676 Root of the
 677 .Pa proto
 678 area of your workspace.
 679 Any shared objects under this directory will be used to establish an
 680 alternative dependency mapping.
 681 .El
 682 If
 683 .Xr ldd 1
 684 supports the
 685 .Fl U
 686 option, it will be used to determine any unreferenced dependencies.
 687 Otherwise
 688 .Xr ldd 1
 689 uses the older
 690 .Fl u
 691 option which only detects unused references.
 692 If the following environment variable exists, and indicates an earlier release
 693 than \fB5.10\fP then
 694 .Xr ldd 1
 695 also falls back to using the
 696 .Fl u
 697 option.
 698 .Bl -tag -width indent
 699 .It Ev RELEASE
 700 The release version number of the environment being built.
 701 .El
 702 .Sh ERROR CONDITIONS
 703 Inspection of an object with
 704 .Xr ldd 1
 705 assumes it is compatible with the machine on which
 706 .Nm check_rtime
 707 is being run.
 708 Incompatible objects such as a 64-bit object encountered on a 32-bit system,
 709 or an i386 object encountered on a sparc system, can not be fully inspected.
 710 These objects are displayed as:
 711 .Pp
 712 .Dl foo: has wrong class or data encoding
 713 .Sh FILES
 714 .Bl -tag -width indent
 715 .It Pa $CODEMGR_WS/exception_list/check_rtime
 716 .It Pa /opt/onbld/etc/exception_list/check_rtime
 717 .El
 718 .Sh SEE ALSO
 719 .Xr crle 1 ,
 720 .Xr elfdump 1 ,
 721 .Xr ld.so.1 1 ,
 722 .Xr ldd 1 ,
 723 .Xr mcs 1 ,
 724 .Xr find_elf 1ONBLD