2 .\"
3 .\" CDDL HEADER START
4 .\"
5 .\" The contents of this file are subject to the terms of the
6 .\" Common Development and Distribution License (the "License").
7 .\" You may not use this file except in compliance with the License.
8 .\"
9 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
10 .\" or http://www.opensolaris.org/os/licensing.
11 .\" See the License for the specific language governing permissions
12 .\" and limitations under the License.
13 .\"
14 .\" When distributing Covered Code, include this CDDL HEADER in each
15 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
16 .\" If applicable, add the following below this CDDL HEADER, with the
17 .\" fields enclosed by brackets "[]" replaced with your own identifying
18 .\" information: Portions Copyright [yyyy] [name of copyright owner]
19 .\"
20 .\" CDDL HEADER END
21 .\"
22 .TH CHECK_RTIME 1ONBLD "Mar 09, 2010"
23 .SH NAME
24 .I check_rtime
25 \- check ELF runtime attributes
26 .SH SYNOPSIS
27 \fBcheck_rtime [-imosv] [-D depfile | -d depdir] [-E errfile] [-e exfile] [-f listfile] [-I infofile] [-w outdir] file | dir, ...\fP
28 .SH DESCRIPTION
29 .LP
30 .I check_rtime
31 attempts to check a number of ELF runtime attributes
32 for consistency with common build rules.
33 These checks involve running \fBldd(1)\fP and
34 \fBelfdump(1)\fP against a family of dynamic objects.
35 A dynamic object can be defined explicitly as a \fIfile\fP
36 or multiple dynamic objects can be located under the directory \fIdir\fP.
37 .LP
38 .I check_rtime
39 is typically called from \fBnightly(1ONBLD)\fP when the \fB-r\fP
40 option is in effect. In this case the dynamic objects under
41 the associated \fIproto\fP area (\fB$ROOT\fP) are checked.
42 .I check_rtime
43 can also be run standalone against any set of dynamic objects.
44 .LP
45 .I check_rtime
46 uses \fBldd(1)\fP to verify dependencies. This implies that
47 by default any object inspected will bind to its dependencies
48 as they are found in the \fBunderlying\fP system. Use of the \fB-D\fP, \fB-d\fP
49 option, or the existence of the environment variables
50 \fB$CODEMGR_WS/$ROOT\fP instruct
51 .I check_rtime
52 to establish an alternative dependency mapping using
53 runtime configuration files generated with \fBcrle(1)\fP.
54 .LP
55 .I check_rtime
56 uses \fBldd(1)\fP to completely relocate any dynamic
57 object and thus detect missing dependencies, unsatisfied
58 symbol relocations, unused and unreferenced dependencies. These checks
59 are carried out for the following reasons:
60 .TP 4
61 \(bu
62 An object that cannot find its dependencies may fail to load
63 at runtime. This error condition often goes unnoticed
64 because the existing use of the object is as a dependency itself,
65 and the objects' dependencies are already satisfied by the
66 caller. However, if the object itself is unable to satisfy its
67 dependencies, its use in new environments may be compromised.
68 .sp
69 A missing or erroneous \fBrunpath\fP is the typical reason why
70 an object can not locate its dependencies. Use of the link-editors
71 \fB-zdefs\fP option when building a shared object ensures required
72 dependencies are established. This flag is inherited from
73 \fB$(DYNFLAGS)\fP in \fIlib/Makefile.lib\fP. Missing dependencies
74 are displayed as:
75 .sp
76 .RS 6
77 foo: bar.so.1 => (file not found) <no -zdefs?>
78 .RE
79 .TP
80 \(bu
81 Unsatisfied symbol relocations indicate that some thread of
82 execution through the object will fail when it is unable to
83 locate a referenced symbol.
84 .sp
85 A missing, or mismatched version of a dependency is the typical
86 reason for unsatisfied symbol relocations (see missing dependency
87 discussion above). Unsatisfied symbol relocations are displayed as:
88 .sp
89 .RS 6
90 foo: symbol not found: bar <no -zdefs?>
91 .RE
92 .RS 4
93 .sp
94 Note: Shared objects can make reference to symbol definitions
95 that are expected to be defined by the caller. To indicate that
96 such symbols are not undefined in the usual sense, you must
97 specify these symbols in a \fImapfile\fP, using the \fBEXTERN\fP
98 or \fBPARENT\fP symbol attribute. Without these symbol attributes,
99 \fBldd(1)\fP is unable to determine the symbols special nature, and
100 .I check_rtime
101 will report these symbols as undefined.
102 .RE
103 .TP
104 \(bu
105 Unused dependencies are wasteful at runtime, as they take time to
106 load and relocate, but will not be used by the calling object. They
107 also result in unnecessary processing at link-edit time.
108 .sp
109 Dependency lists (typically defined via \fB$(LDLIBS)\fP)
110 that have been yanked-and-put
111 between \fIMakefiles\fP without verifying their need, are a typical
112 reason why unused dependencies exist. Unused dependencies are
113 displayed as:
114 .sp
115 .RS 6
116 foo: unused object=bar.so.1 <remove lib or -zignore?>
117 .RE
118 .TP
119 \(bu
120 Unreferenced dependencies are also wasteful at runtime, although not
121 to the extent of unused dependencies. They also result in unnecessary
122 processing at link-edit time.
123 .sp
124 Unreferenced dependency removal guards against a dependency becoming
125 unused when combined with
126 different objects, or as the other object dependencies evolve.
127 Unreferenced dependencies are displayed as:
128 .sp
129 .RS 6
130 foo: unreferenced object=bar.so.1; \\
131 .br
132 unused dependency of libfoo.so.1 \\
133 .br
134 <remove lib or -zignore?>
135 .RE
136 .RS 4
137 .sp
138 See also the section ENVIRONMENT VARIABLES.
139 .RE
140 .TP
141 \(bu
142 Unused search paths are wasteful at runtime.
143 Unused search paths are displayed as:
144 .sp
145 .RS 6
146 foo: unused search path=/usr/foo/lib \\
147 .br
148 (RUNPATH/RPATH from file libfoo.so.1) \\
149 .br
150 <remove search path?>
151 .RE
152 .LP
153 .I check_rtime
154 uses \fBelfdump(1)\fP to look for a concatenated relocation
155 section in shared objects, the existence of text relocations,
156 whether debugging or symbol table information exists, whether
157 applications have a non-executable stack defined, duplicate
158 entries in the symbol sorting sections, and for direct bindings.
159 These checks are carried out for the following reasons:
160 .TP 4
161 \(bu
162 A concatenated relocation section (\fI.SUNW_reloc\fP)
163 provides optimal symbol table
164 access at runtime, and thus reduces the overhead of relocating
165 the shared object. In past releases, the link-edit of a dynamic object with
166 the \fB-z combreloc\fP option was required to generate a combined
167 relocation section. However, with the integration of 6642769, this section
168 combination is a default behavior of the link-editor.
169 .sp
170 In past releases, not inheriting \fB$(DYNFLAGS)\fP from
171 \fIlib/Makefile.lib\fP was the typical reason for not having a
172 concatenated relocation section. The misguided use of the
173 \fB-z nocombreloc\fP option will also prevent the creation of a
174 concatenated relocation section. A missing concatenated relocation section
175 is displayed as:
176 .sp
177 .RS 6
178 foo: .SUNW_reloc section missing <no -zcombreloc?>
179 .RE
180 .TP
181 \(bu
182 Text relocations result in impure text segments. As text segments
183 are typically read-only, they can be shared between numerous processes.
184 If they must be updated as part of the relocation then the updated
185 pages become unsharable and swap space must be allocated to back
186 these pages. These events consume unnecessary system resources and
187 reduce overall system performance.
188 .sp
189 Not inheriting the \fB$(PICS)\fP
190 rules from \fIlib/Makefile.lib\fP is the typical reason for having
191 non-pic code in shared objects. Text relocations are displayed as:
192 .sp
193 .RS 6
194 foo: TEXTREL .dynamic tag <no -Kpic?>
195 .RE
196 .TP
197 \(bu
198 Debugging information is unnecessary in released objects. Although
199 extensive when compiled \fB-g\fP, small quantities of debugging
200 information are stored in \fI.stabs\fP sections under normal
201 compilations. This debugging information is geared towards aiding
202 debuggers locate relocatable objects associated with the dynamic
203 objects being debugged. As relocatable objects aren't made available
204 as part of a software release this information has no use.
205 .sp
206 Not inheriting the correct \fB$(LDFLAGS)\fP from \fIcmd/Makefile.cmd\fP
207 (which asserts \fP-s\fP), or \fB$(POST_PROCESS_SO)\fP (which asserts
208 \fIstrip -x\fP) are typical reasons for not removing debugging
209 information. Note, removal of debugging information is only enabled
210 for release builds. The existence of debugging information is displayed as:
211 .sp
212 .RS 6
213 foo: debugging sections should be deleted \\
214 .br
215 <no strip -x?>
216 .RE
217 .TP
218 \(bu
219 All objects should retain their full \fI.symtab\fP symbol table.
220 Although this consumes disk space, it provides for more extensive stack
221 tracing when debugging user applications.
222 .sp
223 Hard coding a \fI-s\fP flag with \fB$(LDFLAGS)\fP or
224 \fB$(DYNFLAGS)\fP is the typical
225 reason for symbol tables being removed.
226 Objects that do not contain a symbol table are displayed as:
227 .sp
228 .RS 6
229 foo.so.1: symbol table should not be stripped \\
230 .br
231 <remove -s?>
232 .RE
233 .TP
234 \(bu
235 Applications should have a non-executable stack defined to make
236 them less vulnerable to buffer overflow attacks.
237 .sp
238 Not inheriting the \fB$(LDFLAGS)\fP macro in \fIcmd/Makefile.cmd\fP
239 is the typical reason for not having a non-executable stack definition.
240 Applications without this definition are displayed as:
241 .sp
242 .RS 6
243 foo: application requires non-executable stack \\
244 .br
245 .nf
246 <no -Mmapfile_noexstk?>
247 .fi
248 .RE
249 .sp
250 .TP
251 \(bu
252 x86 applications should have a non-executable data segment defined to make
253 them less vulnerable to buffer overflow attacks.
254 .sp
255 Not inheriting the \fB$(LDFLAGS)\fP macro in \fIcmd/Makefile.cmd\fP
256 is the typical reason for not having a non-executable data definition.
257 Applications without this definition are displayed as:
258 .sp
259 .RS 6
260 foo: application requires non-executable data \\
261 .br
262 .nf
263 <no -Mmapfile_noexdata?>
264 .fi
265 .RE
266 .sp
267 .TP
268 \(bu
269 Solaris ELF files contain symbol sort sections used by DTrace to
270 map addresses in memory to the related function or variable symbols. There
271 are two such sections, \fI.SUNW_dynsymsort\fP for
272 regular symbols, and \fI.SUNW_dyntlssort\fP for thread-local
273 symbols. To ensure that the best names are shown for each
274 such address, and that the same name is given across Solaris releases,
275 .I check_rtime
276 enforces the rule that only one symbol can appear in the sort sections for
277 any given address.
278 There are two common ways in which multiple symbols
279 or a given address occur in the ON distribution. The first is from
280 code written in assembly language. The second is as a
281 result of using \fB#pragma weak\fP in C to create weak symbols. The
282 best solution to this
283 situation is to modify the code to avoid symbol aliasing. Alternatively,
284 the \fBNODYNSORT\fP mapfile attribute can be used to eliminate the unwanted
285 symbol.
286 .sp
287 Duplicate entries in a symbol sort section are
288 displayed in one of the following ways, depending on
289 whether the section is for regular or thread-local symbols:
290 .sp
291 .RS 6
292 foo: .SUNW_dynsymsort: duplicate ADDRESS: sym1, sym2
293 .br
294 foo: .SUNW_dyntlssort: duplicate OFFSET: sym1, sym2
295 .RE
296 .sp
297 .TP
298 \(bu
299 \fBOSNet\fP dynamic ELF objects are expected to employ direct bindings whenever
300 feasible. This runtime binding technique helps to avoid accidental
301 interposition problems, and provides a more optimal
302 runtime symbol search model.
303 .sp
304 Not inheriting the correct \fB$(LDFLAGS)\fP from \fIcmd/Makefile.cmd\fP,
305 or the correct \fB$(DYNFLAGS)\fP from \fIlib/Makefile.lib\fP, are the
306 typical reasons for not enabling direct bindings. Dynamic objects that
307 do not contain direct binding information are displayed as:
308 .sp
309 .RS 6
310 foo: object has no direct bindings \\
311 .br
312 .nf
313 <no -B direct or -z direct?>
314 .fi
315 .RE
316
317 .sp
318 .LP
319 .I check_rtime also
320 uses \fBelfdump(1)\fP
321 to display useful dynamic entry information under the \fB-i\fP option.
322 This doesn't necessarily indicate an error condition, but
323 provides information that is often useful for gatekeepers to track
324 changes in a release. Presently the information listed is:
325 .TP
326 \(bu
327 Runpaths are printed for any dynamic object. This is a historic
328 sanity check to insure compiler supplied runpaths (typically from \fBCC\fP)
329 are not recorded in any objects. Runpaths are displayed as:
330 .sp
331 .RS 6
332 foo: RPATH=/usr/bar/lib
333 .RE
334 .TP
335 \(bu
336 Needed dependencies are printed for any dynamic object.
337 In the freeware world this often helps the introducer of a new
338 shared object discover that an existing binary has become its
339 consumer, and thus that binaries package dependencies may require updating.
340 Dependencies are printed as:
341 .sp
342 .RS 6
343 foo: NEEDED=bar.so.1
344 .RE
345 .sp
346 .LP
347 .I check_rtime
348 uses \fBmcs(1)\fP to inspect an object's \fI.comment\fP section.
349 During development, this section contains numerous file identifiers
350 marked with the tag "\fB@(#)\fP". For release builds these sections
351 are deleted and rewritten under control of the \fB$(POST_PROCESS)\fP
352 macro to produce a common release identifier. This identifier
353 typically consists of three lines including a single comment starting
354 with the string "\fB@(#) SunOS\fP". If this common identifier isn't
355 found the following diagnostic is generated:
356 .sp
357 .RS 6
358 foo: non-conforming mcs(1) comment <no $(POST_PROCESS)?>
359 .RE
360 .sp
361 .LP
362 .I check_rtime
363 uses \fBpvs(1)\fP to display version definitions under the \fB-v\fP option.
364 Each symbol defined by the object is shown along with the version it belongs to.
365 Changes to the symbols defined by an object, or the versions they belong to,
366 do not necessarily indicate an error condition, but
367 provides information that is often useful for gatekeepers to track
368 changes in a release.
369 .sp
370 .SH OPTIONS
371 .LP
372 The following options are supported:
373 .TP 4
374 .B \-D depfile
375 Use \fIdepfile\fP to generate an alternative dependency mapping.
376 \fIdepfile\fP must be created by '\fBfind_elf -r\fP'.
377 The \fB-D\fP and \fB-d\fP options are mutually exclusive.
378 .TP
379 .B \-d depdir
380 Use \fIdepdir\fP to generate an alternative dependency mapping.
381 \fBfind_elf(1ONBLD)\fP is used to locate the ELF sharable objects for
382 which alternative mappings are required. The \fB-D\fP and \fB-d\fP options
383 are mutually exclusive.
384 .TP 4
385 .B \-E errfile
386 Direct error messages for the analyzed objects to \fIerrfile\fP instead
387 of stdout.
388 .TP 4
389 .B \-e exfile
390 An exception file is used to exclude objects from
391 the usual rules. See EXCEPTION FILE FORMAT.
392 .TP
393 .B \-f listfile
394 Normally,
395 .I interface_check
396 runs
397 .I find_elf
398 to locate the ELF objects to analyze. The \fB-f\fP option can be
399 used to instead provide a file containing the list of objects to
400 analyze, in the format produced by '\fBfind_elf -r\fP'.
401 .TP
402 .B -I infofile
403 Direct informational messages (\fB-i\fP, and \fB-v\fP options) for the
404 analyzed objects to \fIinfofile\fP instead of stdout.
405 .TP
406 .B \-i
407 Provide dynamic entry information. Presently only dependencies and
408 runpaths are printed.
409 .TP
410 .B \-m
411 Enable \fBmcs(1)\fP checking.
412 .TP
413 .B \-o
414 Produce a one-line output for each condition discovered, prefixed
415 by the objects name. This output style is more terse, but is
416 more appropriate for sorting and diffing with previous build results.
417 .TP
418 .B \-s
419 Determine whether \fI.stabs\fP sections exist.
420 .TP
421 .B \-v
422 Provide version definition information. Each symbol defined by the object
423 is printed along with the version it is assigned to.
424 .TP
425 .B -w outdir
426 Interpret the paths of all input and output files relative to \fIoutdir\fP.
427 .SH EXCEPTION FILE FORMAT
428 Exceptions to the rules enforced by
429 .I check_rtime
430 are specified using an exception file. The \fB-e\fP option is used to
431 specify an explicit exception file. Otherwise, if used in an activated
432 workspace, the default exception file is
433 $CODEMGR_WS/exception_list/check_rtime
434 if that file exists. If not used in an activated workspace, or if
435 $CODEMGR_WS/exception_list/check_rtime does not exist,
436 .I check_rtime
437 will use
438 .I /opt/onbld/etc/exception_list/check_rtime
439 as a fallback default exception file.
440 .P
441 To run
442 .I check_rtime
443 without applying exceptions, specify \fB-e\fP with a value of /dev/null.
444 .P
445 A '#' character at the beginning of a line, or at any point in
446 a line when preceded by whitespace, introduces a comment. Empty lines,
447 and lines containing only comments, are ignored by
448 .I check_rtime.
449 Exceptions are specified as space separated keyword, and \fBperl(1)\fP
450 regular expression:
451 .sp
452 .in +4
453 .nf
454 keyword perl-regex
455 .fi
456 .in -4
457 .sp
458 Since whitespace is used as a separator, the regular
459 expression cannot itself contain whitespace. Use of the \\s character
460 class to represent whitespace within the regular expression is recommended.
461 Before the perl regular expression is used, constructs of the form
462 MACH(dir) are expanded into a regular expression that matches the directory
463 given, as well as any 64-bit architecture subdirectory that
464 might be present (i.e. amd64, sparcv9). For instance, MACH(lib) will
465 match any of the following:
466 .sp
467 .in +4
468 .nf
469 lib
470 lib/amd64
471 lib/sparcv9
472 .fi
473 .in -4
474 .sp
475 The exceptions understood by
476 .I check_rtime
477 are:
478 .sp
479 .ne 2
480 .na
481 \fBEXEC_DATA\fR
482 .ad
483 .RS 17n
484 .sp
485 Executables that are not required to have non-executable writable
486 data segments
487 .RE
488
489 .sp
490 .ne 2
491 .na
492 \fBEXEC_STACK\fR
493 .ad
494 .RS 17n
495 .sp
496 Executables that are not required to have a non-executable stack
497 .RE
498
499 .sp
500 .ne 2
501 .na
502 \fBNOCRLEALT\fR
503 .ad
504 .RS 17n
505 .sp
506 Objects that should be skipped when building the alternative dependency
507 mapping via the \fB-d\fP option.
508 .RE
509
510 .sp
511 .ne 2
512 .na
513 \fBNODIRECT\fR
514 .ad
515 .RS 17n
516 .sp
517 Directories and files that are allowed to have no direct bound symbols.
518 .RE
519
520 .sp
521 .ne 2
522 .na
523 \fBNOSYMSORT\fR
524 .ad
525 .RS 17n
526 .sp
527 Files for which we skip checking of duplicate addresses in the
528 symbol sort sections.
529 .RE
530
531 .sp
532 .ne 2
533 .na
534 \fBOLDDEP\fR
535 .ad
536 .RS 17n
537 .sp
538 Objects that used to contain system functionality that has since
539 migrated to libc. We preserve these libraries as pure filters for
540 backward compatibility but nothing needs to link to them.
541 .RE
542
543 .sp
544 .ne 2
545 .na
546 \fBSKIP\fR
547 .ad
548 .RS 17n
549 .sp
550 Directories and/or individual objects to skip. Note that SKIP should be
551 a last resort, used only when one of the other exceptions will not suffice.
552 .RE
553
554 .sp
555 .ne 2
556 .na
557 \fBSTAB\fR
558 .ad
559 .RS 17n
560 .sp
561 Objects that are allowed to contain debugging information (stabs).
562 .RE
563
564 .sp
565 .ne 2
566 .na
567 \fBTEXTREL\fR
568 .ad
569 .RS 17n
570 .sp
571 Objects for which we allow relocations to the text segment.
572 .RE
573
574 .sp
575 .ne 2
576 .na
577 \fBUNDEF_OBJ\fR
578 .ad
579 .RS 17n
580 .sp
581 Objects that are allowed to be unreferenced.
582 .RE
583
584 .sp
585 .ne 2
586 .na
587 \fBUNDEF_REF\fR
588 .ad
589 .RS 17n
590 .sp
591 Objects that are allowed undefined references.
592 .RE
593
594 .sp
595 .ne 2
596 .na
597 \fBUNUSED_DEPS\fR
598 .ad
599 .RS 17n
600 .sp
601 Objects that are allowed to have unused dependencies.
602 .RE
603
604 .sp
605 .ne 2
606 .na
607 \fBUNUSED_OBJ\fR
608 .ad
609 .RS 17n
610 .sp
611 Objects that are always allowed to be unused dependencies.
612 .RE
613
614 .sp
615 .ne 2
616 .na
617 \fBUNUSED_RPATH\fR
618 .ad
619 .RS 17n
620 .sp
621 Objects that are allowed to have unused runpath directories.
622 .RE
623
624 .SH ALTERNATIVE DEPENDENCY MAPPING
625 .I check_rtime
626 was primarily designed to process a nightly builds \fB$ROOT\fP
627 hierarchy. It is often the case that objects within this hierarchy
628 must bind to dependencies within the same hierarchy to satisfy
629 their requirements.
630 .LP
631 To achieve this,
632 .I check_rtime
633 uses the shared objects specified with the \fB-D\fP or \fB-d\fP options.
634 If neither option is specified, and the \fB$CODEMGR_WS\fP and \fB$ROOT\fP
635 environment variables are defined, the proto area for the workspace
636 is used. The objects found are used
637 to create runtime configuration files via \fBcrle(1)\fP, that establish
638 the new shared objects as alternatives to their underlying system location.
639 .I check_rtime
640 passes these configuration files as \fBLD_CONFIG\fP environment
641 variable settings to \fBldd(1)\fP using its \fB-e\fP option.
642 .LP
643 The effect of these configuration files is that the execution of an
644 object under \fBldd(1)\fP will bind to the dependencies defined as
645 alternatives. Simply put, an object inspected in the \fIproto\fP
646 area will bind to its dependencies found in the \fIproto\fP area.
647 Dependencies that have no alternative mapping will continue to
648 bind to the underlying system.
649 .SH ENVIRONMENT VARIABLES
650 .LP
651 When the \fB-D\fP or \fB-d\fP option isn't in use,
652 .I check_rtime
653 uses the following environment variables to
654 establish an alternative dependency mapping:
655 .LP
656 .B CODEMGR_WS
657 .RS 4
658 The root of your workspace, which is the directory
659 containing \fICodemgr_wsdata\fP. Existence of this environment variable
660 indicates that \fB$ROOT\fP should be investigated.
661 .RE
662 .LP
663 .B ROOT
664 .RS 4
665 Root of the \fIproto\fP area of your workspace. Any shared objects
666 under this directory will be used to establish an alternative dependency
667 mapping.
668 .RE
669 .sp
670 If \fBldd(1)\fP supports the \fB-U\fP option, it will be used to determine
671 any unreferenced dependencies. Otherwise \fBldd(1)\fP uses the older
672 \fB-u\fP option which only detects unused references. If the following
673 environment variable exists, and indicates an earlier release than \fB5.10\fP
674 then \fBldd(1)\fP also falls back to using the \fB-u\fP option.
675 .LP
676 .B RELEASE
677 .RS 4
678 The release version number of the environment being built.
679 .RE
680 .SH ERROR CONDITIONS
681 .LP
682 Inspection of an object with \fBldd(1)\fP assumes it is compatible
683 with the machine on which
684 .I check_rtime
685 is being run. Incompatible objects such as a 64-bit object encountered on
686 a 32-bit system, or an i386 object encountered on a sparc system,
687 can not be fully inspected. These objects are displayed as:
688 .sp
689 .RS 4
690 foo: has wrong class or data encoding
691 .RE
692 .SH FILES
693 .LP
694 .RS 5
695 $CODEMGR_WS/exception_list/check_rtime
696 /opt/onbld/etc/exception_list/check_rtime
697 .SH SEE ALSO
698 .B crle(1),
699 .B elfdump(1),
700 .B find_elf(1ONBLD),
701 .B ldd(1),
702 .B ld.so.1(1),
703 .B mcs(1).
|
2 .\"
3 .\" CDDL HEADER START
4 .\"
5 .\" The contents of this file are subject to the terms of the
6 .\" Common Development and Distribution License (the "License").
7 .\" You may not use this file except in compliance with the License.
8 .\"
9 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
10 .\" or http://www.opensolaris.org/os/licensing.
11 .\" See the License for the specific language governing permissions
12 .\" and limitations under the License.
13 .\"
14 .\" When distributing Covered Code, include this CDDL HEADER in each
15 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
16 .\" If applicable, add the following below this CDDL HEADER, with the
17 .\" fields enclosed by brackets "[]" replaced with your own identifying
18 .\" information: Portions Copyright [yyyy] [name of copyright owner]
19 .\"
20 .\" CDDL HEADER END
21 .\"
22 .Dd February 19, 2018
23 .Dt CHECK_RTIME 1ONBLD
24 .Os
25 .Sh NAME
26 .Nm check_rtime
27 .Nd check ELF runtime attributes
28 .Sh SYNOPSIS
29 .Nm check_rtime
30 .Op Fl imosv
31 .Op Fl D Ar depfile | Fl d depdir
32 .Op Fl E Ar errfile
33 .Op Fl e Ar exfile
34 .Op Fl f Ar listfile
35 .Op Fl I Ar infofile
36 .Op Fl w Ar outdir
37 .Ar file | dir ...
38 .Sh DESCRIPTION
39 .Nm check_rtime
40 attempts to check a number of ELF runtime attributes
41 for consistency with common build rules.
42 These checks involve running
43 .Xr ldd 1
44 and
45 .Xr elfdump 1
46 against a family of dynamic objects.
47 A dynamic object can be defined explicitly as a
48 .Ar file
49 or multiple dynamic objects can be located under the directory
50 .Ar dir .
51 .Pp
52 .Nm check_rtime
53 is typically called from
54 .Xr nightly 1ONBLD
55 when the
56 .Fl r
57 option is in effect.
58 In this case the dynamic objects under
59 the associated
60 .Em proto area
61 .Pq Ev $ROOT
62 are checked.
63 .Nm check_rtime
64 can also be run standalone against any set of dynamic objects.
65 .Pp
66 .Nm check_rtime
67 uses
68 .Xr ldd 1
69 to verify dependencies.
70 This implies that by default any object inspected will bind to its dependencies
71 as they are found in the
72 .Em underlying system .
73 Use of the
74 .Fl D ,
75 .Fl d
76 option, or the existence of the environment variables
77 .Ev $CODEMGR_WS
78 or
79 .Ev $ROOT
80 instruct
81 .Nm check_rtime
82 to establish an alternative dependency mapping using
83 runtime configuration files generated with
84 .Xr crle 1 .
85 .Pp
86 .Nm check_rtime
87 uses
88 .Xr ldd 1
89 to completely relocate any dynamic object and thus detect missing
90 dependencies, unsatisfied symbol relocations, unused and unreferenced
91 dependencies.
92 These checks are carried out for the following reasons:
93 .Bl -bullet
94 .It
95 An object that cannot find its dependencies may fail to load
96 at runtime.
97 This error condition often goes unnoticed because the existing use of the
98 object is as a dependency itself, and the objects' dependencies are already
99 satisfied by the caller.
100 However, if the object itself is unable to satisfy its dependencies, its use
101 in new environments may be compromised.
102 .Pp
103 A missing or erroneous
104 .Em runpath
105 is the typical reason why an object can not locate its dependencies.
106 Use of the link-editors
107 .Fl zdefs
108 option when building a shared object ensures required dependencies are
109 established.
110 This flag is inherited from
111 .Dv $(DYNFLAGS)
112 in
113 .Pa lib/Makefile.lib .
114 Missing dependencies are displayed as:
115 .Pp
116 .Dl foo: bar.so.1 => (file not found) <no -zdefs?>
117 .It
118 Unsatisfied symbol relocations indicate that some thread of
119 execution through the object will fail when it is unable to
120 locate a referenced symbol.
121 .Pp
122 A missing, or mismatched version of a dependency is the typical
123 reason for unsatisfied symbol relocations (see missing dependency
124 discussion above). Unsatisfied symbol relocations are displayed as:
125 .Pp
126 .Dl foo: symbol not found: bar <no -zdefs?>
127 .Pp
128 Note: Shared objects can make reference to symbol definitions
129 that are expected to be defined by the caller.
130 To indicate that such symbols are not undefined in the usual sense, you must
131 specify these symbols in a
132 .Em mapfile ,
133 using the
134 .Va EXTERN
135 or
136 .Va PARENT
137 symbol attributes.
138 Without these symbol attributes,
139 .Xr ldd 1
140 is unable to determine the symbols special nature, and
141 .Nm check_rtime
142 will report these symbols as undefined.
143 .It
144 Unused dependencies are wasteful at runtime, as they take time to
145 load and relocate, but will not be used by the calling object.
146 They also result in unnecessary processing at link-edit time.
147 .Pp
148 Dependency lists (typically defined via
149 .Dv $(LDLIBS) )
150 that have been copy and pasted
151 between
152 .Pa Makefiles
153 without verifying their need, are a typicalreason why unused dependencies
154 exist.
155 Unused dependencies are displayed as:
156 .Pp
157 .Dl foo: unused object=bar.so.1 <remove lib or -zignore?>
158 .It
159 Unreferenced dependencies are also wasteful at runtime, although not
160 to the extent of unused dependencies.
161 They also result in unnecessary processing at link-edit time.
162 .Pp
163 Unreferenced dependency removal guards against a dependency becoming
164 unused when combined with
165 different objects, or as the other object dependencies evolve.
166 Unreferenced dependencies are displayed as:
167 .Bd -literal
168 foo: unreferenced object=bar.so.1; \\
169 unused dependency of libfoo.so.1 \\
170 <remove lib or -zignore?>
171 .Ed
172 .Pp
173 See also the section
174 .Sx ENVIRONMENT VARIABLES .
175 .It
176 Unused search paths are wasteful at runtime.
177 Unused search paths are displayed as:
178 .Bd -literal
179 foo: unused search path=/usr/foo/lib \\
180 (RUNPATH/RPATH from file libfoo.so.1) \\
181 <remove search path?>
182 .Ed
183 .El
184 .Pp
185 .Nm check_rtime
186 uses
187 .Xr elfdump 1
188 to look for a concatenated relocation section in shared objects, the existence
189 of text relocations, whether debugging or symbol table information exists,
190 whether applications have a non-executable stack defined, duplicate entries in
191 the symbol sorting sections, and for direct bindings.
192 These checks are carried out for the following reasons:
193 .Bl -bullet
194 .It
195 A concatenated relocation section
196 .Pq Em .SUNW_reloc
197 provides optimal symbol table access at runtime, and thus reduces the overhead
198 of relocating the shared object.
199 In past releases, the link-edit of a dynamic object with the
200 .Fl z Ar combreloc
201 option was required to generate a combined relocation section.
202 However, with the integration of 6642769, this section combination is a default behavior of
203 the link-editor.
204 .Pp
205 In past releases, not inheriting
206 .Dv $(DYNFLAGS)
207 from
208 .Pa lib/Makefile.lib
209 was the typical reason for not having a concatenated relocation section.
210 The misguided use of the
211 .Fl z Ar nocombreloc
212 option will also prevent the creation of a concatenated relocation section.
213 A missing concatenated relocation section is displayed as:
214 .Pp
215 .Dl foo: .SUNW_reloc section missing <no -zcombreloc?>
216 .It
217 Text relocations result in impure text segments.
218 As text segments are typically read-only, they can be shared between numerous
219 processes.
220 If they must be updated as part of the relocation then the updated pages
221 become unsharable and swap space must be allocated to back these pages.
222 These events consume unnecessary system resources and reduce overall system
223 performance.
224 .Pp
225 Not inheriting the
226 .Dv $(PICS)
227 rules from
228 .Pa lib/Makefile.lib
229 is the typical reason for having non-pic code in shared objects.
230 Text relocations are displayed as:
231 .Pp
232 .Dl foo: TEXTREL .dynamic tag <no -Kpic?>
233 .It
234 Debugging information is unnecessary in released objects.
235 Although extensive when compiled
236 .Fl g ,
237 small quantities of debugging information are stored in
238 .Em .stabs
239 sections under normal compilations.
240 This debugging information is geared towards aiding debuggers locate
241 relocatable objects associated with the dynamic objects being debugged.
242 As relocatable objects aren't made available as part of a software release
243 this information has no use.
244 .Pp
245 Not inheriting the correct
246 .Dv $(LDFLAGS)
247 from
248 .Pa cmd/Makefile.cmd
249 .Pq which asserts Fl s
250 or
251 .Dv $(POST_PROCESS_SO)
252 .Pq which asserts Ic strip -x
253 are typical reasons for not removing debugging information.
254 Note, removal of debugging information is only enabled
255 for release builds.
256 The existence of debugging information is displayed as:
257 .Bd -literal
258 foo: debugging sections should be deleted \\
259 <no strip -x?>
260 .Ed
261 .It
262 All objects should retain their full
263 .Em .symtab
264 symbol table.
265 Although this consumes disk space, it provides for more extensive stack
266 tracing when debugging user applications.
267 .Pp
268 Hard coding a
269 .Fl s
270 flag with
271 .Dv $(LDFLAGS) or
272 .Dv $(DYNFLAGS)
273 is the typical reason for symbol tables being removed.
274 Objects that do not contain a symbol table are displayed as:
275 .Bd -literal
276 foo.so.1: symbol table should not be stripped \\
277 <remove -s?>
278 .Ed
279 .It
280 Applications should have a non-executable stack defined to make
281 them less vulnerable to buffer overflow attacks.
282 .Pp
283 Not inheriting the
284 .Dv $(LDFLAGS)
285 macro in
286 .Pa cmd/Makefile.cmd
287 is the typical reason for not having a non-executable stack definition.
288 Applications without this definition are displayed as:
289 .Bd -literal
290 foo: application requires non-executable stack \\
291 <no -Mmapfile_noexstk?>
292 .Ed
293 .It
294 x86 applications should have a non-executable data segment defined to make
295 them less vulnerable to buffer overflow attacks.
296 .Pp
297 Not inheriting the
298 .Dv $(LDFLAGS)
299 macro in
300 .Pa cmd/Makefile.cmd
301 is the typical reason for not having a non-executable data definition.
302 Applications without this definition are displayed as:
303 .Bd -literal
304 foo: application requires non-executable data \\
305 <no -Mmapfile_noexdata?>
306 .Ed
307 .It
308 Solaris ELF files contain symbol sort sections used by DTrace to
309 map addresses in memory to the related function or variable symbols.
310 There are two such sections,
311 .Em .SUNW_dynsymsort
312 for regular symbols, and
313 .Em .SUNW_dyntlssort
314 for thread-local symbols.
315 To ensure that the best names are shown for each such address, and that the
316 same name is given across Solaris releases,
317 .Nm check_rtime
318 enforces the rule that only one symbol can appear in the sort sections for
319 any given address.
320 There are two common ways in which multiple symbols
321 or a given address occur in the ON distribution.
322 The first is from code written in assembly language.
323 The second is as a result of using
324 .Ic #pragma weak
325 in C to create weak symbols.
326 The best solution to this situation is to modify the code to avoid symbol
327 aliasing.
328 Alternatively, the
329 .Va NODYNSORT
330 mapfile attribute can be used to eliminate the unwanted symbol.
331 .Pp
332 Duplicate entries in a symbol sort section are
333 displayed in one of the following ways, depending on
334 whether the section is for regular or thread-local symbols:
335 .Bd -literal
336 foo: .SUNW_dynsymsort: duplicate ADDRESS: sym1, sym2
337 foo: .SUNW_dyntlssort: duplicate OFFSET: sym1, sym2
338 .Ed
339 .It
340 illumos dynamic ELF objects are expected to employ direct bindings whenever
341 feasible.
342 This runtime binding technique helps to avoid accidental interposition
343 problems, and provides a more optimal runtime symbol search model.
344 .Pp
345 Not inheriting the correct
346 .Dv $(LDFLAGS) from
347 .Pa cmd/Makefile.cmd ,
348 or the correct
349 .Dv $(DYNFLAGS)
350 from
351 .Pa lib/Makefile.lib ,
352 are the typical reasons for not enabling direct bindings.
353 Dynamic objects that do not contain direct binding information are displayed
354 as:
355 .Bd -literal
356 foo: object has no direct bindings \\
357 <no -B direct or -z direct?>
358 .Ed
359 .El
360 .Pp
361 .Nm check_rtime
362 also
363 uses
364 .Xr elfdump 1
365 to display useful dynamic entry information under the
366 .Fl -i
367 option.
368 This doesn't necessarily indicate an error condition, but
369 provides information that is often useful for gatekeepers to track
370 changes in a release.
371 Presently the information listed is:
372 .Bl -bullet
373 .It
374 Runpaths are printed for any dynamic object.
375 This is a historic sanity check to insure compiler supplied runpaths
376 (typically from
377 .Nm CC )
378 are not recorded in any objects.
379 Runpaths are displayed as:
380 .Pp
381 .Dl foo: RPATH=/usr/bar/lib
382 .It
383 Needed dependencies are printed for any dynamic object.
384 In the freeware world this often helps the introducer of a new
385 shared object discover that an existing binary has become its
386 consumer, and thus that binaries package dependencies may require updating.
387 Dependencies are printed as:
388 .Pp
389 .Dl foo: NEEDED=bar.so.1
390 .It
391 Dependencies may be marked as forbidden
392 .Pq see Sx EXCEPTION FILE FORMAT
393 this allows the build to warn should people use them accidentally.
394 Forbidden dependencies are printed as:
395 .Pp
396 .Dl foo: NEEDED=bar.so.1 <forbidden dependency, missing -nodefaultlibs?>
397 .El
398 .Pp
399 .Nm check_rtime
400 uses
401 .Xr mcs 1
402 to inspect an object's
403 .Em .comment
404 section.
405 During development, this section contains numerous file identifiers
406 marked with the tag
407 .Qq @(#) .
408 For release builds these sections are deleted and rewritten under control of
409 the
410 .Dv $(POST_PROCESS)
411 macro to produce a common release identifier.
412 This identifier typically consists of three lines including a single comment
413 starting with the string
414 .Qq @(#) SunOS .
415 If this common identifier isn't found the following diagnostic is generated:
416 .Pp
417 .Dl foo: non-conforming mcs(1) comment <no $(POST_PROCESS)?>
418 .Pp
419 .Nm check_rtime
420 uses
421 .Xr pvs 1
422 to display version definitions under the
423 .Fl v
424 option.
425 Each symbol defined by the object is shown along with the version it belongs to.
426 Changes to the symbols defined by an object, or the versions they belong to,
427 do not necessarily indicate an error condition, but
428 provides information that is often useful for gatekeepers to track
429 changes in a release.
430 .Sh OPTIONS
431 The following options are supported:
432 .Bl -tag -width indent
433 .It Fl D Ar depfile
434 Use
435 .Ar depfile
436 to generate an alternative dependency mapping.
437 .Ar depfile
438 must be created by
439 .Ic find_elf -r .
440 The
441 .Fl D
442 and
443 .Fl d
444 options are mutually exclusive.
445 .It Fl d Ar depfile
446 Use
447 .Ar depdir
448 to generate an alternative dependency mapping.
449 .Xr find_elf 1ONBLD
450 is used to locate the ELF sharable objects for which alternative mappings are
451 required.
452 The
453 .Fl D
454 and
455 .Fl d
456 options are mutually exclusive.
457 .It Fl E Ar errfile
458 Direct error messages for the analyzed objects to
459 .Ar errfile
460 instead of stdout.
461 .It Fl e Ar exfile
462 An exception file is used to exclude objects from
463 the usual rules.
464 See
465 .Sx EXCEPTION FILE FORMAT .
466 .It Fl f Ar listfile
467 Normally,
468 .Ic interface_check
469 runs
470 .Ic find_elf
471 to locate the ELF objects to analyze.
472 The
473 .Fl f
474 option can be used to instead provide a file containing the list of objects to
475 analyze, in the format produced by
476 .Ic find_elf -r .
477 .It Fl I Ar infofile
478 Direct informational messages (
479 .Fl i ,
480 and
481 .Fl v
482 options) for the analyzed objects to
483 .Ar infofile
484 instead of stdout.
485 .It Fl i
486 Provide dynamic entry information.
487 Presently only dependencies and runpaths are printed.
488 .It Fl m
489 Enable
490 .Xr mcs 1
491 checking.
492 .It Fl o
493 Produce a one-line output for each condition discovered, prefixed
494 by the objects name.
495 This output style is more terse, but is more appropriate for sorting and
496 diffing with previous build results.
497 .It Fl s
498 Determine whether
499 .Em .stabs
500 sections exist.
501 .It Fl v
502 Provide version definition information.
503 Each symbol defined by the object is printed along with the version it is
504 assigned to.
505 .It Fl w Ar outdir
506 Interpret the paths of all input and output files relative to
507 .Ar outdir .
508 .El
509 .Sh EXCEPTION FILE FORMAT
510 Exceptions to the rules enforced by
511 .Nm check_rtime
512 are specified using an exception file.
513 The
514 .Fl -e
515 option is used to specify an explicit exception file.
516 Otherwise, if used in an activated workspace, the default exception file is
517 .Pa $CODEMGR_WS/exception_list/check_rtime
518 if that file exists.
519 If not used in an activated workspace, or if
520 .Pa $CODEMGR_WS/exception_list/check_rtime
521 does not exist,
522 .Nm check_rtime
523 will use
524 .Pa /opt/onbld/etc/exception_list/check_rtime
525 as a fallback default exception file.
526 .Pp
527 To run
528 .Nm check_rtime
529 without applying exceptions, specify
530 .Fl e
531 with a value of
532 .Pa /dev/null .
533 .Pp
534 A
535 .Ql #
536 character at the beginning of a line, or at any point in
537 a line when preceded by whitespace, introduces a comment.
538 Empty lines, and lines containing only comments, are ignored by
539 .Nm check_rtime .
540 Exceptions are specified as space separated keyword, and
541 .Xr perl 1
542 regular expression:
543 .Pp
544 .Dl keyword perl-regex
545 .Pp
546 Since whitespace is used as a separator, the regular
547 expression cannot itself contain whitespace.
548 Use of the
549 .Ql \\s
550 character class to represent whitespace within the regular expression is
551 recommended.
552 .Pp
553 Before the perl regular expression is used, constructs of the form
554 .Em MACH(dir)
555 are expanded into a regular expression that matches the directory given, as
556 well as any 64-bit architecture subdirectory that might be present
557 (i.e. amd64, sparcv9). For instance,
558 .Em MACH(lib)
559 will match any of the following:
560 .Bl -tag -width indent
561 .It Pa lib
562 .It Pa lib/amd64
563 .It Pa lib/sparcv9
564 .El
565 .Pp
566 The exceptions understood by
567 .Nm check_rtime
568 are:
569 .Bl -tag -width indent
570 .It EXEC_DATA
571 Executables that are not required to have non-executable writable
572 data segments
573 .It EXEC_STACK
574 Executables that are not required to have a non-executable stack
575 .It NOCRLEALT
576 Objects that should be skipped when building the alternative dependency
577 mapping via the
578 .Fl d
579 option.
580 .It NODIRECT
581 Directories and files that are allowed to have no direct bound symbols.
582 .It NOSYMSORT
583 Files for which we skip checking of duplicate addresses in the
584 symbol sort sections.
585 .It OLDDEP
586 Objects that used to contain system functionality that has since
587 migrated to libc.
588 We preserve these libraries as pure filters for backward compatibility but
589 nothing needs to link to them.
590 .It SKIP
591 Directories and/or individual objects to skip.
592 Note that SKIP should be a last resort, used only when one of the other
593 exceptions will not suffice.
594 .It STAB
595 Objects that are allowed to contain debugging information (stabs).
596 .It TEXTREL
597 Objects for which we allow relocations to the text segment.
598 .It BUNDEF_OBJ
599 Objects that are allowed to be unreferenced.
600 .It UNDEF_REF
601 Objects that are allowed undefined references.
602 .It UNUSED_DEPS
603 Objects that are allowed to have unused dependencies.
604 .It BUNUSED_OBJ
605 Objects that are always allowed to be unused dependencies.
606 .It UNUSED_RPATH
607 Objects that are allowed to have unused runpath directories.
608 .It FORBIDDEN
609 Specifies that dependencies on a given object are forbidden.
610 .It FORBIDDEN_DEP
611 Specifies that a given object is permitted a forbidden dependency.
612 .El
613 .Sh ALTERNATIVE DEPENDENCY MAPPING
614 .Nm check_rtime
615 was primarily designed to process a nightly builds
616 .Ev $ROOT
617 hierarchy.
618 It is often the case that objects within this hierarchy must bind to
619 dependencies within the same hierarchy to satisfy their requirements.
620 .Pp
621 To achieve this,
622 .Nm check_rtime
623 uses the shared objects specified with the
624 .Fl D
625 or
626 .Fl d
627 options.
628 If neither option is specified, and the
629 .Ev $CODEMGR_WS
630 and
631 .Ev $ROOT
632 environment variables are defined, the proto area for the workspace is
633 used.
634 The objects found are used to create runtime configuration files via
635 .Xr crle 1 ,
636 that establish the new shared objects as alternatives to their underlying
637 system location.
638 .Nm check_rtime
639 passes these configuration files as
640 .Ev LD_CONFIG
641 environment variable settings to
642 .Xr ldd 1
643 using its
644 .Fl -e
645 option.
646 .Pp
647 The effect of these configuration files is that the execution of an
648 object under
649 .Xr ldd 1
650 will bind to the dependencies defined as alternatives.
651 Simply put, an object inspected in the
652 .Pa proto
653 area will bind to its dependencies found in the
654 .Pa proto
655 area.
656 Dependencies that have no alternative mapping will continue to bind to the
657 underlying system.
658 .Sh ENVIRONMENT VARIABLES
659 When the
660 .Fl D
661 or
662 .Fl d
663 option isn't in use,
664 .Nm check_rtime
665 uses the following environment variables to
666 establish an alternative dependency mapping:
667 .Bl -tag -width indent
668 .It Ev CODEMGR_WS
669 The root of your workspace, which is the directory
670 containing
671 .Pa .git .
672 Existence of this environment variable indicates that
673 .Ev $ROOT
674 should be investigated.
675 .It Ev ROOT
676 Root of the
677 .Pa proto
678 area of your workspace.
679 Any shared objects under this directory will be used to establish an
680 alternative dependency mapping.
681 .El
682 If
683 .Xr ldd 1
684 supports the
685 .Fl U
686 option, it will be used to determine any unreferenced dependencies.
687 Otherwise
688 .Xr ldd 1
689 uses the older
690 .Fl u
691 option which only detects unused references.
692 If the following environment variable exists, and indicates an earlier release
693 than \fB5.10\fP then
694 .Xr ldd 1
695 also falls back to using the
696 .Fl u
697 option.
698 .Bl -tag -width indent
699 .It Ev RELEASE
700 The release version number of the environment being built.
701 .El
702 .Sh ERROR CONDITIONS
703 Inspection of an object with
704 .Xr ldd 1
705 assumes it is compatible with the machine on which
706 .Nm check_rtime
707 is being run.
708 Incompatible objects such as a 64-bit object encountered on a 32-bit system,
709 or an i386 object encountered on a sparc system, can not be fully inspected.
710 These objects are displayed as:
711 .Pp
712 .Dl foo: has wrong class or data encoding
713 .Sh FILES
714 .Bl -tag -width indent
715 .It Pa $CODEMGR_WS/exception_list/check_rtime
716 .It Pa /opt/onbld/etc/exception_list/check_rtime
717 .El
718 .Sh SEE ALSO
719 .Xr crle 1 ,
720 .Xr elfdump 1 ,
721 .Xr ld.so.1 1 ,
722 .Xr ldd 1 ,
723 .Xr mcs 1 ,
724 .Xr find_elf 1ONBLD
|