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
|