CHECK_RTIME(1ONBLD) illumos Build Tools CHECK_RTIME(1ONBLD)

NAME

check_rtimecheck ELF runtime attributes

SYNOPSIS

check_rtime [-imosv] [-D depfile | -d -depdir] [-E errfile] [-e exfile] [-f listfile] [-I infofile] [-w outdir] file | dir ...

DESCRIPTION

check_rtime attempts to check a number of ELF runtime attributes for consistency with common build rules. These checks involve running ldd(1) and elfdump(1) against a family of dynamic objects. A dynamic object can be defined explicitly as a file or multiple dynamic objects can be located under the directory dir.
check_rtime is typically called from nightly(1ONBLD) when the -r option is in effect. In this case the dynamic objects under the associated proto area ($ROOT) are checked. check_rtime can also be run standalone against any set of dynamic objects.
check_rtime uses ldd(1) to verify dependencies. This implies that by default any object inspected will bind to its dependencies as they are found in the underlying system. Use of the -D, -d option, or the existence of the environment variables $CODEMGR_WS or $ROOT instruct check_rtime to establish an alternative dependency mapping using runtime configuration files generated with crle(1).
check_rtime uses ldd(1) to completely relocate any dynamic object and thus detect missing dependencies, unsatisfied symbol relocations, unused and unreferenced dependencies. These checks are carried out for the following reasons:
check_rtime uses elfdump(1) to look for a concatenated relocation section in shared objects, the existence of text relocations, whether debugging or symbol table information exists, whether applications have a non-executable stack defined, duplicate entries in the symbol sorting sections, and for direct bindings. These checks are carried out for the following reasons:
check_rtime also uses elfdump(1) to display useful dynamic entry information under the --i option. This doesn't necessarily indicate an error condition, but provides information that is often useful for gatekeepers to track changes in a release. Presently the information listed is:
check_rtime uses mcs(1) to inspect an object's .comment section. During development, this section contains numerous file identifiers marked with the tag “@(#)”. For release builds these sections are deleted and rewritten under control of the $(POST_PROCESS) macro to produce a common release identifier. This identifier typically consists of three lines including a single comment starting with the string “@(#) SunOS”. If this common identifier isn't found the following diagnostic is generated:
foo: non-conforming mcs(1) comment <no $(POST_PROCESS)?>
check_rtime uses pvs(1) to display version definitions under the -v option. Each symbol defined by the object is shown along with the version it belongs to. Changes to the symbols defined by an object, or the versions they belong to, do not necessarily indicate an error condition, but provides information that is often useful for gatekeepers to track changes in a release.

OPTIONS

The following options are supported:
 
 
-D depfile
Use depfile to generate an alternative dependency mapping. depfile must be created by find_elf -r. The -D and -d options are mutually exclusive.
 
 
-d depfile
Use depdir to generate an alternative dependency mapping. find_elf(1ONBLD) is used to locate the ELF sharable objects for which alternative mappings are required. The -D and -d options are mutually exclusive.
 
 
-E errfile
Direct error messages for the analyzed objects to errfile instead of stdout.
 
 
-e exfile
An exception file is used to exclude objects from the usual rules. See EXCEPTION FILE FORMAT.
 
 
-f listfile
Normally, interface_check runs find_elf to locate the ELF objects to analyze. The -f option can be used to instead provide a file containing the list of objects to analyze, in the format produced by find_elf -r.
 
 
-I infofile
Direct informational messages ( -i, and -v options) for the analyzed objects to infofile instead of stdout.
 
 
-i
Provide dynamic entry information. Presently only dependencies and runpaths are printed.
 
 
-m
Enable mcs(1) checking.
 
 
-o
Produce a one-line output for each condition discovered, prefixed by the objects name. This output style is more terse, but is more appropriate for sorting and diffing with previous build results.
 
 
-s
Determine whether .stabs sections exist.
 
 
-v
Provide version definition information. Each symbol defined by the object is printed along with the version it is assigned to.
 
 
-w outdir
Interpret the paths of all input and output files relative to outdir.

EXCEPTION FILE FORMAT

Exceptions to the rules enforced by check_rtime are specified using an exception file. The --e option is used to specify an explicit exception file. Otherwise, if used in an activated workspace, the default exception file is $CODEMGR_WS/exception_list/check_rtime if that file exists. If not used in an activated workspace, or if $CODEMGR_WS/exception_list/check_rtime does not exist, check_rtime will use /opt/onbld/etc/exception_list/check_rtime as a fallback default exception file.
To run check_rtime without applying exceptions, specify -e with a value of /dev/null.
A ‘#’ character at the beginning of a line, or at any point in a line when preceded by whitespace, introduces a comment. Empty lines, and lines containing only comments, are ignored by check_rtime. Exceptions are specified as space separated keyword, and perl(1) regular expression:
keyword perl-regex
Since whitespace is used as a separator, the regular expression cannot itself contain whitespace. Use of the ‘’ character class to represent whitespace within the regular expression is recommended.
Before the perl regular expression is used, constructs of the form MACH(dir) are expanded into a regular expression that matches the directory given, as well as any 64-bit architecture subdirectory that might be present (i.e. amd64, sparcv9). For instance, MACH(lib) will match any of the following:
 
 
lib
 
lib/amd64
 
lib/sparcv9
 
The exceptions understood by check_rtime are:
 
 
EXEC_DATA
Executables that are not required to have non-executable writable data segments
 
 
EXEC_STACK
Executables that are not required to have a non-executable stack
 
 
NOCRLEALT
Objects that should be skipped when building the alternative dependency mapping via the -d option.
 
 
NODIRECT
Directories and files that are allowed to have no direct bound symbols.
 
 
NOSYMSORT
Files for which we skip checking of duplicate addresses in the symbol sort sections.
 
 
OLDDEP
Objects that used to contain system functionality that has since migrated to libc. We preserve these libraries as pure filters for backward compatibility but nothing needs to link to them.
 
 
SKIP
Directories and/or individual objects to skip. Note that SKIP should be a last resort, used only when one of the other exceptions will not suffice.
 
 
STAB
Objects that are allowed to contain debugging information (stabs).
 
 
TEXTREL
Objects for which we allow relocations to the text segment.
 
 
BUNDEF_OBJ
Objects that are allowed to be unreferenced.
 
 
UNDEF_REF
Objects that are allowed undefined references.
 
 
UNUSED_DEPS
Objects that are allowed to have unused dependencies.
 
 
BUNUSED_OBJ
Objects that are always allowed to be unused dependencies.
 
 
UNUSED_RPATH
Objects that are allowed to have unused runpath directories.
 
 
FORBIDDEN
Specifies that dependencies on a given object are forbidden.
 
 
FORBIDDEN_DEP
Specifies that a given object is permitted a forbidden dependency.

ALTERNATIVE DEPENDENCY MAPPING

check_rtime was primarily designed to process a nightly builds $ROOT hierarchy. It is often the case that objects within this hierarchy must bind to dependencies within the same hierarchy to satisfy their requirements.
To achieve this, check_rtime uses the shared objects specified with the -D or -d options. If neither option is specified, and the $CODEMGR_WS and $ROOT environment variables are defined, the proto area for the workspace is used. The objects found are used to create runtime configuration files via crle(1), that establish the new shared objects as alternatives to their underlying system location. check_rtime passes these configuration files as LD_CONFIG environment variable settings to ldd(1) using its --e option.
The effect of these configuration files is that the execution of an object under ldd(1) will bind to the dependencies defined as alternatives. Simply put, an object inspected in the proto area will bind to its dependencies found in the proto area. Dependencies that have no alternative mapping will continue to bind to the underlying system.

ENVIRONMENT VARIABLES

When the -D or -d option isn't in use, check_rtime uses the following environment variables to establish an alternative dependency mapping:
 
 
CODEMGR_WS
The root of your workspace, which is the directory containing .git. Existence of this environment variable indicates that $ROOT should be investigated.
 
 
ROOT
Root of the proto area of your workspace. Any shared objects under this directory will be used to establish an alternative dependency mapping.
If ldd(1) supports the -U option, it will be used to determine any unreferenced dependencies. Otherwise ldd(1) uses the older -u option which only detects unused references. If the following environment variable exists, and indicates an earlier release than 5.10 then ldd(1) also falls back to using the -u option.
 
 
RELEASE
The release version number of the environment being built.

ERROR CONDITIONS

Inspection of an object with ldd(1) assumes it is compatible with the machine on which check_rtime is being run. Incompatible objects such as a 64-bit object encountered on a 32-bit system, or an i386 object encountered on a sparc system, can not be fully inspected. These objects are displayed as:
foo: has wrong class or data encoding

FILES

 
 
$CODEMGR_WS/exception_list/check_rtime
 
/opt/onbld/etc/exception_list/check_rtime
 

SEE ALSO

crle(1), elfdump(1), ld.so.1(1), ldd(1), mcs(1), find_elf(1ONBLD)
February 19, 2018 illumos