Print this page
9139 check_rtime should be able to forbid libraries
9140 check_rtime should learn libnsl is safe now
9141 check_rtime exceptions could be cleaner
   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)
   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