1 CHECK_RTIME(1ONBLD)           illumos Build Tools          CHECK_RTIME(1ONBLD)
   3 NAME
   4      check_rtime - check ELF runtime attributes
   7      check_rtime [-imosv] [-D depfile | -d -depdir] [-E errfile] [-e exfile]
   8                  [-f listfile] [-I infofile] [-w outdir] file | dir ...
  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.
  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.
  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).
  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:
  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.
  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:
  47                foo: bar.so.1 =>      (file not found) <no -zdefs?>
  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.
  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:
  57                foo: symbol not found: bar <no -zdefs?>
  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.
  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.
  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:
  76                foo: unused object=bar.so.1 <remove lib or -zignore?>
  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.
  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:
  86          foo: unreferenced object=bar.so.1;  \
  87              unused dependency of libfoo.so.1  \
  88              <remove lib or -zignore?>
  90          See also the section ENVIRONMENT VARIABLES.
  92      o   Unused search paths are wasteful at runtime.  Unused search paths are
  93          displayed as:
  95          foo: unused search path=/usr/foo/lib  \
  96              (RUNPATH/RPATH from file libfoo.so.1)  \
  97              <remove search path?>
  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:
 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.
 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:
 120                foo: .SUNW_reloc section missing <no -zcombreloc?>
 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.
 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:
 133                foo: TEXTREL .dynamic tag <no -Kpic?>
 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.
 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:
 149          foo: debugging sections should be deleted  \
 150              <no strip -x?>
 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.
 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:
 160          foo.so.1: symbol table should not be stripped  \
 161              <remove -s?>
 163      o   Applications should have a non-executable stack defined to make them
 164          less vulnerable to buffer overflow attacks.
 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:
 170          foo: application requires non-executable stack \
 171                  <no -Mmapfile_noexstk?>
 173      o   x86 applications should have a non-executable data segment defined to
 174          make them less vulnerable to buffer overflow attacks.
 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:
 180          foo: application requires non-executable data \
 181                  <no -Mmapfile_noexdata?>
 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.
 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:
 202          foo: .SUNW_dynsymsort: duplicate ADDRESS: sym1, sym2
 203          foo: .SUNW_dyntlssort: duplicate OFFSET: sym1, sym2
 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.
 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:
 215          foo: object has no direct bindings \
 216                  <no -B      direct or -z direct?>
 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:
 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:
 228                foo: RPATH=/usr/bar/lib
 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:
 236                foo: NEEDED=bar.so.1
 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:
 242                foo: NEEDED=bar.so.1     <forbidden dependency, missing
 243                -nodefaultlibs?>
 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:
 253            foo: non-conforming mcs(1) comment <no $(POST_PROCESS)?>
 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.
 263      The following options are supported:
 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.
 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.
 276      -E errfile
 277              Direct error messages for the analyzed objects to errfile instead
 278              of stdout.
 280      -e exfile
 281              An exception file is used to exclude objects from the usual
 282              rules.  See EXCEPTION FILE FORMAT.
 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.
 290      -I infofile
 291              Direct informational messages ( -i, and -v options) for the
 292              analyzed objects to infofile instead of stdout.
 294      -i      Provide dynamic entry information.  Presently only dependencies
 295              and runpaths are printed.
 297      -m      Enable mcs(1) checking.
 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.
 304      -s      Determine whether .stabs sections exist.
 306      -v      Provide version definition information.  Each symbol defined by
 307              the object is printed along with the version it is assigned to.
 309      -w outdir
 310              Interpret the paths of all input and output files relative to
 311              outdir.
 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.
 323      To run check_rtime without applying exceptions, specify -e with a value
 324      of /dev/null.
 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:
 331            keyword perl-regex
 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.
 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:
 343      lib
 345      lib/amd64
 347      lib/sparcv9
 349      The exceptions understood by check_rtime are:
 351      EXEC_DATA
 352              Executables that are not required to have non-executable writable
 353              data segments
 355      EXEC_STACK
 356              Executables that are not required to have a non-executable stack
 358      NOCRLEALT
 359              Objects that should be skipped when building the alternative
 360              dependency mapping via the -d option.
 362      NODIRECT
 363              Directories and files that are allowed to have no direct bound
 364              symbols.
 366      NOSYMSORT
 367              Files for which we skip checking of duplicate addresses in the
 368              symbol sort sections.
 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.
 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.
 378      STAB    Objects that are allowed to contain debugging information
 379              (stabs).
 381      TEXTREL
 382              Objects for which we allow relocations to the text segment.
 384      BUNDEF_OBJ
 385              Objects that are allowed to be unreferenced.
 387      UNDEF_REF
 388              Objects that are allowed undefined references.
 390      UNUSED_DEPS
 391              Objects that are allowed to have unused dependencies.
 393      BUNUSED_OBJ
 394              Objects that are always allowed to be unused dependencies.
 396      UNUSED_RPATH
 397              Objects that are allowed to have unused runpath directories.
 399      FORBIDDEN
 400              Specifies that dependencies on a given object are forbidden.
 403              Specifies that a given object is permitted a forbidden
 404              dependency.
 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.
 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.
 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.
 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:
 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.
 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.
 445      RELEASE
 446              The release version number of the environment being built.
 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:
 455            foo: has wrong class or data encoding
 457 FILES
 458      $CODEMGR_WS/exception_list/check_rtime
 460      /opt/onbld/etc/exception_list/check_rtime
 463      crle(1), elfdump(1), ld.so.1(1), ldd(1), mcs(1), find_elf(1ONBLD)
 465 illumos                        February 19, 2018                       illumos