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 "09 March 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 .LP
29 .SH DESCRIPTION
30 .IX "OS-Net build tools" "check_rtime" "" "\fBcheck_rtime\fP"
31 .LP
32 .I check_rtime
33 attempts to check a number of ELF runtime attributes
34 for consistency with common build rules.
35 These checks involve running \fBldd(1)\fP and
36 \fBelfdump(1)\fP against a family of dynamic objects.
37 A dynamic object can be defined explicitly as a \fIfile\fP
38 or multiple dynamic objects can be located under the directory \fIdir\fP.
39 .LP
40 .I check_rtime
41 is typically called from \fBnightly(1ONBLD)\fP when the \fB-r\fP
42 option is in effect. In this case the dynamic objects under
43 the associated \fIproto\fP area (\fB$ROOT\fP) are checked.
44 .I check_rtime
45 can also be run standalone against any set of dynamic objects.
46 .LP
47 .I check_rtime
48 uses \fBldd(1)\fP to verify dependencies. This implies that
49 by default any object inspected will bind to its dependencies
50 as they are found in the \fBunderlying\fP system. Use of the \fB-D\fP, \fB-d\fP
227 reason for symbol tables being removed.
228 Objects that do not contain a symbol table are displayed as:
229 .sp
230 .RS 6
231 foo.so.1: symbol table should not be stripped \\
232 .br
233 <remove -s?>
234 .RE
235 .TP
236 \(bu
237 Applications should have a non-executable stack defined to make
238 them less vulnerable to buffer overflow attacks.
239 .sp
240 Not inheriting the \fB$(LDFLAGS)\fP macro in \fIcmd/Makefile.cmd\fP
241 is the typical reason for not having a non-executable stack definition.
242 Applications without this definition are displayed as:
243 .sp
244 .RS 6
245 foo: application requires non-executable stack \\
246 .br
247 <no -Mmapfile_noexstk?>
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 <no -Mmapfile_noexdata?>
263 .RE
264 .sp
265 .TP
266 \(bu
267 Solaris ELF files contain symbol sort sections used by DTrace to
268 map addresses in memory to the related function or variable symbols. There
269 are two such sections, \fI.SUNW_dynsymsort\fP for
270 regular symbols, and \fI.SUNW_dyntlssort\fP for thread-local
271 symbols. To ensure that the best names are shown for each
272 such address, and that the same name is given across Solaris releases,
273 .I check_rtime
274 enforces the rule that only one symbol can appear in the sort sections for
275 any given address.
276 There are two common ways in which multiple symbols
277 or a given address occur in the ON distribution. The first is from
278 code written in assembly language. The second is as a
279 result of using \fB#pragma weak\fP in C to create weak symbols. The
280 best solution to this
281 situation is to modify the code to avoid symbol aliasing. Alternatively,
282 the \fBNODYNSORT\fP mapfile attribute can be used to eliminate the unwanted
290 foo: .SUNW_dynsymsort: duplicate ADDRESS: sym1, sym2
291 .br
292 foo: .SUNW_dyntlssort: duplicate OFFSET: sym1, sym2
293 .RE
294 .sp
295 .TP
296 \(bu
297 \fBOSNet\fP dynamic ELF objects are expected to employ direct bindings whenever
298 feasible. This runtime binding technique helps to avoid accidental
299 interposition problems, and provides a more optimal
300 runtime symbol search model.
301 .sp
302 Not inheriting the correct \fB$(LDFLAGS)\fP from \fIcmd/Makefile.cmd\fP,
303 or the correct \fB$(DYNFLAGS)\fP from \fIlib/Makefile.lib\fP, are the
304 typical reasons for not enabling direct bindings. Dynamic objects that
305 do not contain direct binding information are displayed as:
306 .sp
307 .RS 6
308 foo: object has no direct bindings \\
309 .br
310 <no -B direct or -z direct?>
311 .RE
312
313 .sp
314 .LP
315 .I check_rtime also
316 uses \fBelfdump(1)\fP
317 to display useful dynamic entry information under the \fB-i\fP option.
318 This doesn't necessarily indicate an error condition, but
319 provides information that is often useful for gatekeepers to track
320 changes in a release. Presently the information listed is:
321 .TP
322 \(bu
323 Runpaths are printed for any dynamic object. This is a historic
324 sanity check to insure compiler supplied runpaths (typically from \fBCC\fP)
325 are not recorded in any objects. Runpaths are displayed as:
326 .sp
327 .RS 6
328 foo: RPATH=/usr/bar/lib
329 .RE
330 .TP
345 During development, this section contains numerous file identifiers
346 marked with the tag "\fB@(#)\fP". For release builds these sections
347 are deleted and rewritten under control of the \fB$(POST_PROCESS)\fP
348 macro to produce a common release identifier. This identifier
349 typically consists of three lines including a single comment starting
350 with the string "\fB@(#) SunOS\fP". If this common identifier isn't
351 found the following diagnostic is generated:
352 .sp
353 .RS 6
354 foo: non-conforming mcs(1) comment <no $(POST_PROCESS)?>
355 .RE
356 .sp
357 .LP
358 .I check_rtime
359 uses \fBpvs(1)\fP to display version definitions under the \fB-v\fP option.
360 Each symbol defined by the object is shown along with the version it belongs to.
361 Changes to the symbols defined by an object, or the versions they belong to,
362 do not necessarily indicate an error condition, but
363 provides information that is often useful for gatekeepers to track
364 changes in a release.
365 .RE
366 .sp
367 .LP
368 .SH OPTIONS
369 .LP
370 The following options are supported:
371 .TP 4
372 .B \-D depfile
373 Use \fIdepfile\fP to generate an alternative dependency mapping.
374 \fIdepfile\fP must be created by '\fBfind_elf -r\fP'.
375 The \fB-D\fP and \fB-d\fP options are mutually exclusive.
376 .TP
377 .B \-d depdir
378 Use \fIdepdir\fP to generate an alternative dependency mapping.
379 \fBfind_elf(1ONBLD)\fP is used to locate the ELF sharable objects for
380 which alternative mappings are required. The \fB-D\fP and \fB-d\fP options
381 are mutually exclusive.
382 .TP 4
383 .B \-E errfile
384 Direct error messages for the analyzed objects to \fIerrfile\fP instead
385 of stdout.
386 .TP 4
387 .B \-e exfile
405 Provide dynamic entry information. Presently only dependencies and
406 runpaths are printed.
407 .TP
408 .B \-m
409 Enable \fBmcs(1)\fP checking.
410 .TP
411 .B \-o
412 Produce a one-line output for each condition discovered, prefixed
413 by the objects name. This output style is more terse, but is
414 more appropriate for sorting and diffing with previous build results.
415 .TP
416 .B \-s
417 Determine whether \fI.stabs\fP sections exist.
418 .TP
419 .B \-v
420 Provide version definition information. Each symbol defined by the object
421 is printed along with the version it is assigned to.
422 .TP
423 .B -w outdir
424 Interpret the paths of all input and output files relative to \fIoutdir\fP.
425 .LP
426 .SH EXCEPTION FILE FORMAT
427 Exceptions to the rules enforced by
428 .I check_rtime
429 are specified using an exception file. The \fB-e\fP option is used to
430 specify an explicit exception file. Otherwise, if used in an activated
431 workspace, the default exception file is
432 $CODEMGR_WS/exception_list/check_rtime
433 if that file exists. If not used in an activated workspace, or if
434 $CODEMGR_WS/exception_list/check_rtime does not exist,
435 .I check_rtime
436 will use
437 .I /opt/onbld/etc/exception_list/check_rtime
438 as a fallback default exception file.
439 .p
440 To run
441 .I check_rtime
442 without applying exceptions, specify \fB-e\fP with a value of /dev/null.
443 .P
444 A '#' character at the beginning of a line, or at any point in
445 a line when preceded by whitespace, introduces a comment. Empty lines,
446 and lines containing only comments, are ignored by
447 .I check_rtime.
448 Exceptions are specified as space separated keyword, and \fBperl(1)\fP
449 regular expression:
450 .sp
451 .in +4
452 .nf
453 keyword perl-regex
454 .fi
455 .in -4
456 .sp
457 Since whitespace is used as a separator, the regular
458 expression cannot itself contain whitespace. Use of the \\s character
459 class to represent whitespace within the regular expression is recommended.
460 Before the perl regular expression is used, constructs of the form
461 MACH(dir) are expanded into a regular expression that matches the directory
462 given, as well as any 64-bit architecture subdirectory that
463 might be present (i.e. amd64, sparcv9). For instance, MACH(lib) will
464 match any of the following:
465 .sp
466 .in +4
467 .nf
468 lib
469 lib/amd64
470 lib/sparcv9
471 .fi
472 .in -4
473 .sp
474 The exceptions understood by
475 .I check_rtime
476 are:
477 .sp
478 .ne 2
479 .mk
480 .na
481 \fBEXEC_DATA\fR
482 .ad
483 .RS 17n
484 .rt
485 .sp
486 Executables that are not required to have non-executable writable
487 data segments
488 .RE
489
490 .sp
491 .ne 2
492 .mk
493 .na
494 \fBEXEC_STACK\fR
495 .ad
496 .RS 17n
497 .rt
498 .sp
499 Executables that are not required to have a non-executable stack
500 .RE
501
502 .sp
503 .ne 2
504 .mk
505 .na
506 \fBNOCRLEALT\fR
507 .ad
508 .RS 17n
509 .rt
510 .sp
511 Objects that should be skipped when building the alternative dependency
512 mapping via the \fB-d\fP option.
513 .RE
514
515 .sp
516 .ne 2
517 .mk
518 .na
519 \fBNODIRECT\fR
520 .ad
521 .RS 17n
522 .rt
523 .sp
524 Directories and files that are allowed to have no direct bound symbols.
525 .RE
526
527 .sp
528 .ne 2
529 .mk
530 .na
531 \fBNOSYMSORT\fR
532 .ad
533 .RS 17n
534 .rt
535 .sp
536 Files for which we skip checking of duplicate addresses in the
537 symbol sort sections.
538 .RE
539
540 .sp
541 .ne 2
542 .mk
543 .na
544 \fBOLDDEP\fR
545 .ad
546 .RS 17n
547 .rt
548 .sp
549 Objects that used to contain system functionality that has since
550 migrated to libc. We preserve these libraries as pure filters for
551 backward compatibility but nothing needs to link to them.
552 .RE
553
554 .sp
555 .ne 2
556 .mk
557 .na
558 \fBSKIP\fR
559 .ad
560 .RS 17n
561 .rt
562 .sp
563 Directories and/or individual objects to skip. Note that SKIP should be
564 a last resort, used only when one of the other exceptions will not suffice.
565 .RE
566
567 .sp
568 .ne 2
569 .mk
570 .na
571 \fBSTAB\fR
572 .ad
573 .RS 17n
574 .rt
575 .sp
576 Objects that are allowed to contain debugging information (stabs).
577 .RE
578
579 .sp
580 .ne 2
581 .mk
582 .na
583 \fBTEXTREL\fR
584 .ad
585 .RS 17n
586 .rt
587 .sp
588 Objects for which we allow relocations to the text segment.
589 .RE
590
591 .sp
592 .ne 2
593 .mk
594 .na
595 \fBUNDEF_OBJ\fR
596 .ad
597 .RS 17n
598 .rt
599 .sp
600 Objects that are allowed to be unreferenced.
601 .RE
602
603 .sp
604 .ne 2
605 .mk
606 .na
607 \fBUNDEF_REF\fR
608 .ad
609 .RS 17n
610 .rt
611 .sp
612 Objects that are allowed undefined references.
613 .RE
614
615 .sp
616 .ne 2
617 .mk
618 .na
619 \fBUNUSED_DEPS\fR
620 .ad
621 .RS 17n
622 .rt
623 .sp
624 Objects that are allowed to have unused dependencies.
625 .RE
626
627 .sp
628 .ne 2
629 .mk
630 .na
631 \fBUNUSED_OBJ\fR
632 .ad
633 .RS 17n
634 .rt
635 .sp
636 Objects that are always allowed to be unused dependencies.
637 .RE
638
639 .sp
640 .ne 2
641 .mk
642 .na
643 \fBUNUSED_RPATH\fR
644 .ad
645 .RS 17n
646 .rt
647 .sp
648 Objects that are allowed to have unused runpath directories.
649 .RE
650
651 .LP
652 .SH ALTERNATIVE DEPENDENCY MAPPING
653 .I check_rtime
654 was primarily designed to process a nightly builds \fB$ROOT\fP
655 hierarchy. It is often the case that objects within this hierarchy
656 must bind to dependencies within the same hierarchy to satisfy
657 their requirements.
658 .LP
659 To achieve this,
660 .I check_rtime
661 uses the shared objects specified with the \fB-D\fP or \fB-d\fP options.
662 If neither option is specified, and the \fB$CODEMGR_WS\fP and \fB$ROOT\fP
663 environment variables are defined, the proto area for the workspace
664 is used. The objects found are used
665 to create runtime configuration files via \fBcrle(1)\fP, that establish
666 the new shared objects as alternatives to their underlying system location.
667 .I check_rtime
668 passes these configuration files as \fBLD_CONFIG\fP environment
669 variable settings to \fBldd(1)\fP using its \fB-e\fP option.
670 .LP
671 The effect of these configuration files is that the execution of an
672 object under \fBldd(1)\fP will bind to the dependencies defined as
673 alternatives. Simply put, an object inspected in the \fIproto\fP
674 area will bind to its dependencies found in the \fIproto\fP area.
675 Dependencies that have no alternative mapping will continue to
676 bind to the underlying system.
677 .LP
678 .SH ENVIRONMENT VARIABLES
679 .LP
680 When the \fB-D\fP or \fB-d\fP option isn't in use,
681 .I check_rtime
682 uses the following environment variables to
683 establish an alternative dependency mapping:
684 .LP
685 .B CODEMGR_WS
686 .RS 4
687 The root of your workspace, which is the directory
688 containing \fICodemgr_wsdata\fP. Existence of this environment variable
689 indicates that \fB$ROOT\fP should be investigated.
690 .RE
691 .LP
692 .B ROOT
693 .RS 4
694 Root of the \fIproto\fP area of your workspace. Any shared objects
695 under this directory will be used to establish an alternative dependency
696 mapping.
697 .RE
698 .sp
699 If \fBldd(1)\fP supports the \fB-U\fP option, it will be used to determine
700 any unreferenced dependencies. Otherwise \fBldd(1)\fP uses the older
701 \fB-u\fP option which only detects unused references. If the following
702 environment variable exists, and indicates an earlier release than \fB5.10\fP
703 then \fBldd(1)\fP also falls back to using the \fB-u\fP option.
704 .RE
705 .LP
706 .B RELEASE
707 .RS 4
708 The release version number of the environment being built.
709 .RE
710 .SH ERROR CONDITIONS
711 .LP
712 Inspection of an object with \fBldd(1)\fP assumes it is compatible
713 with the machine on which
714 .I check_rtime
715 is being run. Incompatible objects such as a 64-bit object encountered on
716 a 32-bit system, or an i386 object encountered on a sparc system,
717 can not be fully inspected. These objects are displayed as:
718 .sp
719 .RS 4
720 foo: has wrong class or data encoding
721 .RE
722 .LP
723 .SH FILES
724 .LP
725 .RS 5
726 $CODEMGR_WS/exception_list/check_rtime
727 /opt/onbld/etc/exception_list/check_rtime
728 .SH SEE ALSO
729 .B crle(1),
730 .B elfdump(1),
731 .B find_elf(1ONBLD),
732 .B ldd(1),
733 .B ld.so.1(1),
734 .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 .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
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
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
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
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).
|