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

Split Close
Expand all
Collapse all
          --- old/usr/src/tools/scripts/check_rtime.1onbld.man.txt
          +++ new/usr/src/tools/scripts/check_rtime.1onbld.man.txt
   1    1  CHECK_RTIME(1ONBLD)           illumos Build Tools          CHECK_RTIME(1ONBLD)
   2    2  
   3      -
   4      -
   5    3  NAME
   6      -       check_rtime - check ELF runtime attributes
        4 +     check_rtime - check ELF runtime attributes
   7    5  
   8    6  SYNOPSIS
   9      -       check_rtime [-imosv] [-D depfile | -d depdir] [-E errfile] [-e exfile]
  10      -       [-f listfile] [-I infofile] [-w outdir] file | dir, ...
        7 +     check_rtime [-imosv] [-D depfile | -d -depdir] [-E errfile] [-e exfile]
        8 +                 [-f listfile] [-I infofile] [-w outdir] file | dir ...
  11    9  
  12   10  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      -
       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.
 268  261  
 269  262  OPTIONS
 270      -       The following options are supported:
      263 +     The following options are supported:
 271  264  
 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.
      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.
 318  312  
 319  313  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      -
      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.
 366  322  
 367      -       NOCRLEALT
      323 +     To run check_rtime without applying exceptions, specify -e with a value
      324 +     of /dev/null.
 368  325  
 369      -                        Objects that should be skipped when building the
 370      -                        alternative dependency mapping via the -d option.
      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:
 371  330  
      331 +           keyword perl-regex
 372  332  
 373      -       NODIRECT
      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.
 374  336  
 375      -                        Directories and files that are allowed to have no
 376      -                        direct bound symbols.
      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:
 377  342  
      343 +     lib
 378  344  
 379      -       NOSYMSORT
      345 +     lib/amd64
 380  346  
 381      -                        Files for which we skip checking of duplicate
 382      -                        addresses in the symbol sort sections.
      347 +     lib/sparcv9
 383  348  
      349 +     The exceptions understood by check_rtime are:
 384  350  
 385      -       OLDDEP
      351 +     EXEC_DATA
      352 +             Executables that are not required to have non-executable writable
      353 +             data segments
 386  354  
 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.
      355 +     EXEC_STACK
      356 +             Executables that are not required to have a non-executable stack
 391  357  
      358 +     NOCRLEALT
      359 +             Objects that should be skipped when building the alternative
      360 +             dependency mapping via the -d option.
 392  361  
 393      -       SKIP
      362 +     NODIRECT
      363 +             Directories and files that are allowed to have no direct bound
      364 +             symbols.
 394  365  
 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.
      366 +     NOSYMSORT
      367 +             Files for which we skip checking of duplicate addresses in the
      368 +             symbol sort sections.
 398  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.
 399  373  
 400      -       STAB
      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.
 401  377  
 402      -                        Objects that are allowed to contain debugging
 403      -                        information (stabs).
      378 +     STAB    Objects that are allowed to contain debugging information
      379 +             (stabs).
 404  380  
      381 +     TEXTREL
      382 +             Objects for which we allow relocations to the text segment.
 405  383  
 406      -       TEXTREL
      384 +     BUNDEF_OBJ
      385 +             Objects that are allowed to be unreferenced.
 407  386  
 408      -                        Objects for which we allow relocations to the text
 409      -                        segment.
      387 +     UNDEF_REF
      388 +             Objects that are allowed undefined references.
 410  389  
      390 +     UNUSED_DEPS
      391 +             Objects that are allowed to have unused dependencies.
 411  392  
 412      -       UNDEF_OBJ
      393 +     BUNUSED_OBJ
      394 +             Objects that are always allowed to be unused dependencies.
 413  395  
 414      -                        Objects that are allowed to be unreferenced.
      396 +     UNUSED_RPATH
      397 +             Objects that are allowed to have unused runpath directories.
 415  398  
      399 +     FORBIDDEN
      400 +             Specifies that dependencies on a given object are forbidden.
 416  401  
 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      -
      402 +     FORBIDDEN_DEP
      403 +             Specifies that a given object is permitted a forbidden
      404 +             dependency.
 438  405  
 439  406  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.
      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.
 460  426  
 461  427  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:
      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:
 464  430  
 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.
      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.
 480  444  
 481      -       RELEASE
 482      -           The release version number of the environment being built.
      445 +     RELEASE
      446 +             The release version number of the environment being built.
 483  447  
 484  448  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:
      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:
 490  454  
 491  455             foo: has wrong class or data encoding
 492  456  
 493  457  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).
      458 +     $CODEMGR_WS/exception_list/check_rtime
 499  459  
      460 +     /opt/onbld/etc/exception_list/check_rtime
 500  461  
      462 +SEE ALSO
      463 +     crle(1), elfdump(1), ld.so.1(1), ldd(1), mcs(1), find_elf(1ONBLD)
 501  464  
 502      -                                 March 9, 2010             CHECK_RTIME(1ONBLD)
      465 +illumos                        February 19, 2018                       illumos
    
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX