Print this page
XXXX check_rtime should be able to forbid libraries
XXXX check_rtime needs to learn libnsl is safe now
XXXX check_rtime could use MACH() more thoroughly
XXXX check_rtime exceptions could be tidied up.
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/tools/scripts/check_rtime.1onbld.man.txt
+++ new/usr/src/tools/scripts/check_rtime.1onbld.man.txt
1 1 CHECK_RTIME(1ONBLD) illumos Build Tools CHECK_RTIME(1ONBLD)
2 2
3 -
4 -
5 3 NAME
6 - check_rtime - check ELF runtime attributes
4 + check_rtime - check ELF runtime attributes
7 5
8 6 SYNOPSIS
9 - check_rtime [-imosv] [-D depfile | -d depdir] [-E errfile] [-e exfile]
10 - [-f listfile] [-I infofile] [-w outdir] file | dir, ...
7 + check_rtime [-imosv] [-D depfile | -d -depdir] [-E errfile] [-e exfile]
8 + [-f listfile] [-I infofile] [-w outdir] file | dir ...
11 9
12 10 DESCRIPTION
13 - check_rtime attempts to check a number of ELF runtime attributes for
14 - consistency with common build rules. These checks involve running
15 - ldd(1) and elfdump(1) against a family of dynamic objects. A dynamic
16 - object can be defined explicitly as a file or multiple dynamic objects
17 - can be located under the directory dir.
18 -
19 - check_rtime is typically called from nightly(1ONBLD) when the -r option
20 - is in effect. In this case the dynamic objects under the associated
21 - proto area ($ROOT) are checked. check_rtime can also be run standalone
22 - against any set of dynamic objects.
23 -
24 - check_rtime uses ldd(1) to verify dependencies. This implies that by
25 - default any object inspected will bind to its dependencies as they are
26 - found in the underlying system. Use of the -D, -d option, or the
27 - existence of the environment variables $CODEMGR_WS/$ROOT instruct
28 - check_rtime to establish an alternative dependency mapping using
29 - runtime configuration files generated with crle(1).
30 -
31 - check_rtime uses ldd(1) to completely relocate any dynamic object and
32 - thus detect missing dependencies, unsatisfied symbol relocations,
33 - unused and unreferenced dependencies. These checks are carried out for
34 - the following reasons:
35 -
36 - o An object that cannot find its dependencies may fail to load at
37 - runtime. This error condition often goes unnoticed because the
38 - existing use of the object is as a dependency itself, and the
39 - objects' dependencies are already satisfied by the caller.
40 - However, if the object itself is unable to satisfy its
41 - dependencies, its use in new environments may be compromised.
42 -
43 - A missing or erroneous runpath is the typical reason why an object
44 - can not locate its dependencies. Use of the link-editors -zdefs
45 - option when building a shared object ensures required dependencies
46 - are established. This flag is inherited from $(DYNFLAGS) in
47 - lib/Makefile.lib. Missing dependencies are displayed as:
48 -
49 - foo: bar.so.1 => (file not found) <no -zdefs?>
50 -
51 - o Unsatisfied symbol relocations indicate that some thread of
52 - execution through the object will fail when it is unable to locate
53 - a referenced symbol.
54 -
55 - A missing, or mismatched version of a dependency is the typical
56 - reason for unsatisfied symbol relocations (see missing dependency
57 - discussion above). Unsatisfied symbol relocations are displayed as:
58 -
59 - foo: symbol not found: bar <no -zdefs?>
60 -
61 - Note: Shared objects can make reference to symbol definitions that
62 - are expected to be defined by the caller. To indicate that such
63 - symbols are not undefined in the usual sense, you must specify
64 - these symbols in a mapfile, using the EXTERN or PARENT symbol
65 - attribute. Without these symbol attributes, ldd(1) is unable to
66 - determine the symbols special nature, and check_rtime will report
67 - these symbols as undefined.
68 -
69 - o Unused dependencies are wasteful at runtime, as they take time to
70 - load and relocate, but will not be used by the calling object.
71 - They also result in unnecessary processing at link-edit time.
72 -
73 - Dependency lists (typically defined via $(LDLIBS)) that have been
74 - yanked-and-put between Makefiles without verifying their need, are
75 - a typical reason why unused dependencies exist. Unused
76 - dependencies are displayed as:
77 -
78 - foo: unused object=bar.so.1 <remove lib or -zignore?>
79 -
80 - o Unreferenced dependencies are also wasteful at runtime, although
81 - not to the extent of unused dependencies. They also result in
82 - unnecessary processing at link-edit time.
83 -
84 - Unreferenced dependency removal guards against a dependency
85 - becoming unused when combined with different objects, or as the
86 - other object dependencies evolve. Unreferenced dependencies are
87 - displayed as:
88 -
89 - foo: unreferenced object=bar.so.1; \
90 - unused dependency of libfoo.so.1 \
91 - <remove lib or -zignore?>
92 -
93 - See also the section ENVIRONMENT VARIABLES.
94 -
95 - o Unused search paths are wasteful at runtime. Unused search paths
96 - are displayed as:
97 -
98 - foo: unused search path=/usr/foo/lib \
99 - (RUNPATH/RPATH from file libfoo.so.1) \
100 - <remove search path?>
101 -
102 - check_rtime uses elfdump(1) to look for a concatenated relocation
103 - section in shared objects, the existence of text relocations, whether
104 - debugging or symbol table information exists, whether applications have
105 - a non-executable stack defined, duplicate entries in the symbol sorting
106 - sections, and for direct bindings. These checks are carried out for
107 - the following reasons:
108 -
109 - o A concatenated relocation section (.SUNW_reloc) provides optimal
110 - symbol table access at runtime, and thus reduces the overhead of
111 - relocating the shared object. In past releases, the link-edit of a
112 - dynamic object with the -z combreloc option was required to
113 - generate a combined relocation section. However, with the
114 - integration of 6642769, this section combination is a default
115 - behavior of the link-editor.
116 -
117 - In past releases, not inheriting $(DYNFLAGS) from lib/Makefile.lib
118 - was the typical reason for not having a concatenated relocation
119 - section. The misguided use of the -z nocombreloc option will also
120 - prevent the creation of a concatenated relocation section. A
121 - missing concatenated relocation section is displayed as:
122 -
123 - foo: .SUNW_reloc section missing <no -zcombreloc?>
124 -
125 - o Text relocations result in impure text segments. As text segments
126 - are typically read-only, they can be shared between numerous
127 - processes. If they must be updated as part of the relocation then
128 - the updated pages become unsharable and swap space must be
129 - allocated to back these pages. These events consume unnecessary
130 - system resources and reduce overall system performance.
131 -
132 - Not inheriting the $(PICS) rules from lib/Makefile.lib is the
133 - typical reason for having non-pic code in shared objects. Text
134 - relocations are displayed as:
135 -
136 - foo: TEXTREL .dynamic tag <no -Kpic?>
137 -
138 - o Debugging information is unnecessary in released objects. Although
139 - extensive when compiled -g, small quantities of debugging
140 - information are stored in .stabs sections under normal
141 - compilations. This debugging information is geared towards aiding
142 - debuggers locate relocatable objects associated with the dynamic
143 - objects being debugged. As relocatable objects aren't made
144 - available as part of a software release this information has no
145 - use.
146 -
147 - Not inheriting the correct $(LDFLAGS) from cmd/Makefile.cmd (which
148 - asserts -s), or $(POST_PROCESS_SO) (which asserts strip -x) are
149 - typical reasons for not removing debugging information. Note,
150 - removal of debugging information is only enabled for release
151 - builds. The existence of debugging information is displayed as:
152 -
153 - foo: debugging sections should be deleted \
154 - <no strip -x?>
155 -
156 - o All objects should retain their full .symtab symbol table.
157 - Although this consumes disk space, it provides for more extensive
158 - stack tracing when debugging user applications.
159 -
160 - Hard coding a -s flag with $(LDFLAGS) or $(DYNFLAGS) is the typical
161 - reason for symbol tables being removed. Objects that do not
162 - contain a symbol table are displayed as:
163 -
164 - foo.so.1: symbol table should not be stripped \
165 - <remove -s?>
166 -
167 - o Applications should have a non-executable stack defined to make
168 - them less vulnerable to buffer overflow attacks.
169 -
170 - Not inheriting the $(LDFLAGS) macro in cmd/Makefile.cmd is the
171 - typical reason for not having a non-executable stack definition.
172 - Applications without this definition are displayed as:
173 -
174 - foo: application requires non-executable stack \
175 - <no -Mmapfile_noexstk?>
176 -
177 -
178 - o x86 applications should have a non-executable data segment defined
179 - to make them less vulnerable to buffer overflow attacks.
180 -
181 - Not inheriting the $(LDFLAGS) macro in cmd/Makefile.cmd is the
182 - typical reason for not having a non-executable data definition.
183 - Applications without this definition are displayed as:
184 -
185 - foo: application requires non-executable data \
186 - <no -Mmapfile_noexdata?>
187 -
188 -
189 - o Solaris ELF files contain symbol sort sections used by DTrace to
190 - map addresses in memory to the related function or variable
191 - symbols. There are two such sections, .SUNW_dynsymsort for regular
192 - symbols, and .SUNW_dyntlssort for thread-local symbols. To ensure
193 - that the best names are shown for each such address, and that the
194 - same name is given across Solaris releases, check_rtime enforces
195 - the rule that only one symbol can appear in the sort sections for
196 - any given address. There are two common ways in which multiple
197 - symbols or a given address occur in the ON distribution. The first
198 - is from code written in assembly language. The second is as a
199 - result of using #pragma weak in C to create weak symbols. The best
200 - solution to this situation is to modify the code to avoid symbol
201 - aliasing. Alternatively, the NODYNSORT mapfile attribute can be
202 - used to eliminate the unwanted symbol.
203 -
204 - Duplicate entries in a symbol sort section are displayed in one of
205 - the following ways, depending on whether the section is for regular
206 - or thread-local symbols:
207 -
208 - foo: .SUNW_dynsymsort: duplicate ADDRESS: sym1, sym2
209 - foo: .SUNW_dyntlssort: duplicate OFFSET: sym1, sym2
210 -
211 -
212 - o OSNet dynamic ELF objects are expected to employ direct bindings
213 - whenever feasible. This runtime binding technique helps to avoid
214 - accidental interposition problems, and provides a more optimal
215 - runtime symbol search model.
216 -
217 - Not inheriting the correct $(LDFLAGS) from cmd/Makefile.cmd, or the
218 - correct $(DYNFLAGS) from lib/Makefile.lib, are the typical reasons
219 - for not enabling direct bindings. Dynamic objects that do not
220 - contain direct binding information are displayed as:
221 -
222 - foo: object has no direct bindings \
223 - <no -B direct or -z direct?>
224 -
225 -
226 -
227 - check_rtime also uses elfdump(1) to display useful dynamic entry
228 - information under the -i option. This doesn't necessarily indicate an
229 - error condition, but provides information that is often useful for
230 - gatekeepers to track changes in a release. Presently the information
231 - listed is:
232 -
233 - o Runpaths are printed for any dynamic object. This is a historic
234 - sanity check to insure compiler supplied runpaths (typically
235 - from CC) are not recorded in any objects. Runpaths are
236 - displayed as:
237 -
238 - foo: RPATH=/usr/bar/lib
239 -
240 - o Needed dependencies are printed for any dynamic object. In the
241 - freeware world this often helps the introducer of a new shared
242 - object discover that an existing binary has become its consumer,
243 - and thus that binaries package dependencies may require
244 - updating. Dependencies are printed as:
245 -
246 - foo: NEEDED=bar.so.1
247 -
248 -
249 - check_rtime uses mcs(1) to inspect an object's .comment section.
250 - During development, this section contains numerous file identifiers
251 - marked with the tag "@(#)". For release builds these sections are
252 - deleted and rewritten under control of the $(POST_PROCESS) macro to
253 - produce a common release identifier. This identifier typically
254 - consists of three lines including a single comment starting with the
255 - string "@(#) SunOS". If this common identifier isn't found the
256 - following diagnostic is generated:
257 -
258 - foo: non-conforming mcs(1) comment <no $(POST_PROCESS)?>
259 -
260 -
261 - check_rtime uses pvs(1) to display version definitions under the -v
262 - option. Each symbol defined by the object is shown along with the
263 - version it belongs to. Changes to the symbols defined by an object, or
264 - the versions they belong to, do not necessarily indicate an error
265 - condition, but provides information that is often useful for
266 - gatekeepers to track changes in a release.
267 -
11 + check_rtime attempts to check a number of ELF runtime attributes for
12 + consistency with common build rules. These checks involve running ldd(1)
13 + and elfdump(1) against a family of dynamic objects. A dynamic object can
14 + be defined explicitly as a file or multiple dynamic objects can be
15 + located under the directory dir.
16 +
17 + check_rtime is typically called from nightly(1ONBLD) when the -r option
18 + is in effect. In this case the dynamic objects under the associated
19 + proto area ($ROOT) are checked. check_rtime can also be run standalone
20 + against any set of dynamic objects.
21 +
22 + check_rtime uses ldd(1) to verify dependencies. This implies that by
23 + default any object inspected will bind to its dependencies as they are
24 + found in the underlying system. Use of the -D, -d option, or the
25 + existence of the environment variables $CODEMGR_WS or $ROOT instruct
26 + check_rtime to establish an alternative dependency mapping using runtime
27 + configuration files generated with crle(1).
28 +
29 + check_rtime uses ldd(1) to completely relocate any dynamic object and
30 + thus detect missing dependencies, unsatisfied symbol relocations, unused
31 + and unreferenced dependencies. These checks are carried out for the
32 + following reasons:
33 +
34 + o An object that cannot find its dependencies may fail to load at
35 + runtime. This error condition often goes unnoticed because the
36 + existing use of the object is as a dependency itself, and the
37 + objects' dependencies are already satisfied by the caller. However,
38 + if the object itself is unable to satisfy its dependencies, its use
39 + in new environments may be compromised.
40 +
41 + A missing or erroneous runpath is the typical reason why an object
42 + can not locate its dependencies. Use of the link-editors -zdefs
43 + option when building a shared object ensures required dependencies
44 + are established. This flag is inherited from $(DYNFLAGS) in
45 + lib/Makefile.lib. Missing dependencies are displayed as:
46 +
47 + foo: bar.so.1 => (file not found) <no -zdefs?>
48 +
49 + o Unsatisfied symbol relocations indicate that some thread of execution
50 + through the object will fail when it is unable to locate a referenced
51 + symbol.
52 +
53 + A missing, or mismatched version of a dependency is the typical
54 + reason for unsatisfied symbol relocations (see missing dependency
55 + discussion above). Unsatisfied symbol relocations are displayed as:
56 +
57 + foo: symbol not found: bar <no -zdefs?>
58 +
59 + Note: Shared objects can make reference to symbol definitions that
60 + are expected to be defined by the caller. To indicate that such
61 + symbols are not undefined in the usual sense, you must specify these
62 + symbols in a mapfile, using the EXTERN or PARENT symbol attributes.
63 + Without these symbol attributes, ldd(1) is unable to determine the
64 + symbols special nature, and check_rtime will report these symbols as
65 + undefined.
66 +
67 + o Unused dependencies are wasteful at runtime, as they take time to
68 + load and relocate, but will not be used by the calling object. They
69 + also result in unnecessary processing at link-edit time.
70 +
71 + Dependency lists (typically defined via $(LDLIBS)) that have been
72 + copy and pasted between Makefiles without verifying their need, are a
73 + typicalreason why unused dependencies exist. Unused dependencies are
74 + displayed as:
75 +
76 + foo: unused object=bar.so.1 <remove lib or -zignore?>
77 +
78 + o Unreferenced dependencies are also wasteful at runtime, although not
79 + to the extent of unused dependencies. They also result in
80 + unnecessary processing at link-edit time.
81 +
82 + Unreferenced dependency removal guards against a dependency becoming
83 + unused when combined with different objects, or as the other object
84 + dependencies evolve. Unreferenced dependencies are displayed as:
85 +
86 + foo: unreferenced object=bar.so.1; \
87 + unused dependency of libfoo.so.1 \
88 + <remove lib or -zignore?>
89 +
90 + See also the section ENVIRONMENT VARIABLES.
91 +
92 + o Unused search paths are wasteful at runtime. Unused search paths are
93 + displayed as:
94 +
95 + foo: unused search path=/usr/foo/lib \
96 + (RUNPATH/RPATH from file libfoo.so.1) \
97 + <remove search path?>
98 +
99 + check_rtime uses elfdump(1) to look for a concatenated relocation section
100 + in shared objects, the existence of text relocations, whether debugging
101 + or symbol table information exists, whether applications have a non-
102 + executable stack defined, duplicate entries in the symbol sorting
103 + sections, and for direct bindings. These checks are carried out for the
104 + following reasons:
105 +
106 + o A concatenated relocation section (.SUNW_reloc) provides optimal
107 + symbol table access at runtime, and thus reduces the overhead of
108 + relocating the shared object. In past releases, the link-edit of a
109 + dynamic object with the -z combreloc option was required to generate
110 + a combined relocation section. However, with the integration of
111 + 6642769, this section combination is a default behavior of the link-
112 + editor.
113 +
114 + In past releases, not inheriting $(DYNFLAGS) from lib/Makefile.lib
115 + was the typical reason for not having a concatenated relocation
116 + section. The misguided use of the -z nocombreloc option will also
117 + prevent the creation of a concatenated relocation section. A missing
118 + concatenated relocation section is displayed as:
119 +
120 + foo: .SUNW_reloc section missing <no -zcombreloc?>
121 +
122 + o Text relocations result in impure text segments. As text segments
123 + are typically read-only, they can be shared between numerous
124 + processes. If they must be updated as part of the relocation then
125 + the updated pages become unsharable and swap space must be allocated
126 + to back these pages. These events consume unnecessary system
127 + resources and reduce overall system performance.
128 +
129 + Not inheriting the $(PICS) rules from lib/Makefile.lib is the typical
130 + reason for having non-pic code in shared objects. Text relocations
131 + are displayed as:
132 +
133 + foo: TEXTREL .dynamic tag <no -Kpic?>
134 +
135 + o Debugging information is unnecessary in released objects. Although
136 + extensive when compiled -g, small quantities of debugging information
137 + are stored in .stabs sections under normal compilations. This
138 + debugging information is geared towards aiding debuggers locate
139 + relocatable objects associated with the dynamic objects being
140 + debugged. As relocatable objects aren't made available as part of a
141 + software release this information has no use.
142 +
143 + Not inheriting the correct $(LDFLAGS) from cmd/Makefile.cmd (which
144 + asserts -s) or $(POST_PROCESS_SO) (which asserts strip -x) are
145 + typical reasons for not removing debugging information. Note,
146 + removal of debugging information is only enabled for release builds.
147 + The existence of debugging information is displayed as:
148 +
149 + foo: debugging sections should be deleted \
150 + <no strip -x?>
151 +
152 + o All objects should retain their full .symtab symbol table. Although
153 + this consumes disk space, it provides for more extensive stack
154 + tracing when debugging user applications.
155 +
156 + Hard coding a -s flag with $(LDFLAGS) or $(DYNFLAGS) is the typical
157 + reason for symbol tables being removed. Objects that do not contain
158 + a symbol table are displayed as:
159 +
160 + foo.so.1: symbol table should not be stripped \
161 + <remove -s?>
162 +
163 + o Applications should have a non-executable stack defined to make them
164 + less vulnerable to buffer overflow attacks.
165 +
166 + Not inheriting the $(LDFLAGS) macro in cmd/Makefile.cmd is the
167 + typical reason for not having a non-executable stack definition.
168 + Applications without this definition are displayed as:
169 +
170 + foo: application requires non-executable stack \
171 + <no -Mmapfile_noexstk?>
172 +
173 + o x86 applications should have a non-executable data segment defined to
174 + make them less vulnerable to buffer overflow attacks.
175 +
176 + Not inheriting the $(LDFLAGS) macro in cmd/Makefile.cmd is the
177 + typical reason for not having a non-executable data definition.
178 + Applications without this definition are displayed as:
179 +
180 + foo: application requires non-executable data \
181 + <no -Mmapfile_noexdata?>
182 +
183 + o Solaris ELF files contain symbol sort sections used by DTrace to map
184 + addresses in memory to the related function or variable symbols.
185 + There are two such sections, .SUNW_dynsymsort for regular symbols,
186 + and .SUNW_dyntlssort for thread-local symbols. To ensure that the
187 + best names are shown for each such address, and that the same name is
188 + given across Solaris releases, check_rtime enforces the rule that
189 + only one symbol can appear in the sort sections for any given
190 + address. There are two common ways in which multiple symbols or a
191 + given address occur in the ON distribution. The first is from code
192 + written in assembly language. The second is as a result of using
193 + #pragma weak in C to create weak symbols. The best solution to this
194 + situation is to modify the code to avoid symbol aliasing.
195 + Alternatively, the NODYNSORT mapfile attribute can be used to
196 + eliminate the unwanted symbol.
197 +
198 + Duplicate entries in a symbol sort section are displayed in one of
199 + the following ways, depending on whether the section is for regular
200 + or thread-local symbols:
201 +
202 + foo: .SUNW_dynsymsort: duplicate ADDRESS: sym1, sym2
203 + foo: .SUNW_dyntlssort: duplicate OFFSET: sym1, sym2
204 +
205 + o illumos dynamic ELF objects are expected to employ direct bindings
206 + whenever feasible. This runtime binding technique helps to avoid
207 + accidental interposition problems, and provides a more optimal
208 + runtime symbol search model.
209 +
210 + Not inheriting the correct $(LDFLAGS) from cmd/Makefile.cmd, or the
211 + correct $(DYNFLAGS) from lib/Makefile.lib, are the typical reasons
212 + for not enabling direct bindings. Dynamic objects that do not
213 + contain direct binding information are displayed as:
214 +
215 + foo: object has no direct bindings \
216 + <no -B direct or -z direct?>
217 +
218 + check_rtime also uses elfdump(1) to display useful dynamic entry
219 + information under the --i option. This doesn't necessarily indicate an
220 + error condition, but provides information that is often useful for
221 + gatekeepers to track changes in a release. Presently the information
222 + listed is:
223 +
224 + o Runpaths are printed for any dynamic object. This is a historic
225 + sanity check to insure compiler supplied runpaths (typically from CC)
226 + are not recorded in any objects. Runpaths are displayed as:
227 +
228 + foo: RPATH=/usr/bar/lib
229 +
230 + o Needed dependencies are printed for any dynamic object. In the
231 + freeware world this often helps the introducer of a new shared object
232 + discover that an existing binary has become its consumer, and thus
233 + that binaries package dependencies may require updating.
234 + Dependencies are printed as:
235 +
236 + foo: NEEDED=bar.so.1
237 +
238 + o Dependencies may be marked as forbidden (see EXCEPTION FILE FORMAT)
239 + this allows the build to warn should people use them accidentally.
240 + Forbidden dependencies are printed as:
241 +
242 + foo: NEEDED=bar.so.1 <forbidden dependency, missing
243 + -nodefaultlibs?>
244 +
245 + check_rtime uses mcs(1) to inspect an object's .comment section. During
246 + development, this section contains numerous file identifiers marked with
247 + the tag "@(#)". For release builds these sections are deleted and
248 + rewritten under control of the $(POST_PROCESS) macro to produce a common
249 + release identifier. This identifier typically consists of three lines
250 + including a single comment starting with the string "@(#) SunOS". If
251 + this common identifier isn't found the following diagnostic is generated:
252 +
253 + foo: non-conforming mcs(1) comment <no $(POST_PROCESS)?>
254 +
255 + check_rtime uses pvs(1) to display version definitions under the -v
256 + option. Each symbol defined by the object is shown along with the
257 + version it belongs to. Changes to the symbols defined by an object, or
258 + the versions they belong to, do not necessarily indicate an error
259 + condition, but provides information that is often useful for gatekeepers
260 + to track changes in a release.
268 261
269 262 OPTIONS
270 - The following options are supported:
263 + The following options are supported:
271 264
272 - -D depfile
273 - Use depfile to generate an alternative dependency mapping. depfile
274 - must be created by 'find_elf -r'. The -D and -d options are
275 - mutually exclusive.
276 -
277 - -d depdir
278 - Use depdir to generate an alternative dependency mapping.
279 - find_elf(1ONBLD) is used to locate the ELF sharable objects for
280 - which alternative mappings are required. The -D and -d options are
281 - mutually exclusive.
282 -
283 - -E errfile
284 - Direct error messages for the analyzed objects to errfile instead
285 - of stdout.
286 -
287 - -e exfile
288 - An exception file is used to exclude objects from the usual rules.
289 - See EXCEPTION FILE FORMAT.
290 -
291 - -f listfile
292 - Normally, interface_check runs find_elf to locate the ELF objects
293 - to analyze. The -f option can be used to instead provide a file
294 - containing the list of objects to analyze, in the format produced
295 - by 'find_elf -r'.
296 -
297 - -I infofile
298 - Direct informational messages (-i, and -v options) for the analyzed
299 - objects to infofile instead of stdout.
300 -
301 - -i Provide dynamic entry information. Presently only dependencies and
302 - runpaths are printed.
303 -
304 - -m Enable mcs(1) checking.
305 -
306 - -o Produce a one-line output for each condition discovered, prefixed
307 - by the objects name. This output style is more terse, but is more
308 - appropriate for sorting and diffing with previous build results.
309 -
310 - -s Determine whether .stabs sections exist.
311 -
312 - -v Provide version definition information. Each symbol defined by the
313 - object is printed along with the version it is assigned to.
314 -
315 - -w outdir
316 - Interpret the paths of all input and output files relative to
317 - outdir.
265 + -D depfile
266 + Use depfile to generate an alternative dependency mapping.
267 + depfile must be created by find_elf -r. The -D and -d options
268 + are mutually exclusive.
269 +
270 + -d depfile
271 + Use depdir to generate an alternative dependency mapping.
272 + find_elf(1ONBLD) is used to locate the ELF sharable objects for
273 + which alternative mappings are required. The -D and -d options
274 + are mutually exclusive.
275 +
276 + -E errfile
277 + Direct error messages for the analyzed objects to errfile instead
278 + of stdout.
279 +
280 + -e exfile
281 + An exception file is used to exclude objects from the usual
282 + rules. See EXCEPTION FILE FORMAT.
283 +
284 + -f listfile
285 + Normally, interface_check runs find_elf to locate the ELF objects
286 + to analyze. The -f option can be used to instead provide a file
287 + containing the list of objects to analyze, in the format produced
288 + by find_elf -r.
289 +
290 + -I infofile
291 + Direct informational messages ( -i, and -v options) for the
292 + analyzed objects to infofile instead of stdout.
293 +
294 + -i Provide dynamic entry information. Presently only dependencies
295 + and runpaths are printed.
296 +
297 + -m Enable mcs(1) checking.
298 +
299 + -o Produce a one-line output for each condition discovered, prefixed
300 + by the objects name. This output style is more terse, but is
301 + more appropriate for sorting and diffing with previous build
302 + results.
303 +
304 + -s Determine whether .stabs sections exist.
305 +
306 + -v Provide version definition information. Each symbol defined by
307 + the object is printed along with the version it is assigned to.
308 +
309 + -w outdir
310 + Interpret the paths of all input and output files relative to
311 + outdir.
318 312
319 313 EXCEPTION FILE FORMAT
320 - Exceptions to the rules enforced by check_rtime are specified using an
321 - exception file. The -e option is used to specify an explicit exception
322 - file. Otherwise, if used in an activated workspace, the default
323 - exception file is $CODEMGR_WS/exception_list/check_rtime if that file
324 - exists. If not used in an activated workspace, or if
325 - $CODEMGR_WS/exception_list/check_rtime does not exist, check_rtime will
326 - use /opt/onbld/etc/exception_list/check_rtime as a fallback default
327 - exception file.
328 -
329 - To run check_rtime without applying exceptions, specify -e with a value
330 - of /dev/null.
331 -
332 - A '#' character at the beginning of a line, or at any point in a line
333 - when preceded by whitespace, introduces a comment. Empty lines, and
334 - lines containing only comments, are ignored by check_rtime. Exceptions
335 - are specified as space separated keyword, and perl(1) regular
336 - expression:
337 -
338 - keyword perl-regex
339 -
340 - Since whitespace is used as a separator, the regular expression cannot
341 - itself contain whitespace. Use of the \s character class to represent
342 - whitespace within the regular expression is recommended. Before the
343 - perl regular expression is used, constructs of the form MACH(dir) are
344 - expanded into a regular expression that matches the directory given, as
345 - well as any 64-bit architecture subdirectory that might be present
346 - (i.e. amd64, sparcv9). For instance, MACH(lib) will match any of the
347 - following:
348 -
349 - lib
350 - lib/amd64
351 - lib/sparcv9
352 -
353 - The exceptions understood by check_rtime are:
354 -
355 - EXEC_DATA
356 -
357 - Executables that are not required to have non-
358 - executable writable data segments
359 -
360 -
361 - EXEC_STACK
362 -
363 - Executables that are not required to have a non-
364 - executable stack
365 -
314 + Exceptions to the rules enforced by check_rtime are specified using an
315 + exception file. The --e option is used to specify an explicit exception
316 + file. Otherwise, if used in an activated workspace, the default
317 + exception file is $CODEMGR_WS/exception_list/check_rtime if that file
318 + exists. If not used in an activated workspace, or if
319 + $CODEMGR_WS/exception_list/check_rtime does not exist, check_rtime will
320 + use /opt/onbld/etc/exception_list/check_rtime as a fallback default
321 + exception file.
366 322
367 - NOCRLEALT
323 + To run check_rtime without applying exceptions, specify -e with a value
324 + of /dev/null.
368 325
369 - Objects that should be skipped when building the
370 - alternative dependency mapping via the -d option.
326 + A `#' character at the beginning of a line, or at any point in a line
327 + when preceded by whitespace, introduces a comment. Empty lines, and
328 + lines containing only comments, are ignored by check_rtime. Exceptions
329 + are specified as space separated keyword, and perl(1) regular expression:
371 330
331 + keyword perl-regex
372 332
373 - NODIRECT
333 + Since whitespace is used as a separator, the regular expression cannot
334 + itself contain whitespace. Use of the `' character class to represent
335 + whitespace within the regular expression is recommended.
374 336
375 - Directories and files that are allowed to have no
376 - direct bound symbols.
337 + Before the perl regular expression is used, constructs of the form
338 + MACH(dir) are expanded into a regular expression that matches the
339 + directory given, as well as any 64-bit architecture subdirectory that
340 + might be present (i.e. amd64, sparcv9). For instance, MACH(lib) will
341 + match any of the following:
377 342
343 + lib
378 344
379 - NOSYMSORT
345 + lib/amd64
380 346
381 - Files for which we skip checking of duplicate
382 - addresses in the symbol sort sections.
347 + lib/sparcv9
383 348
349 + The exceptions understood by check_rtime are:
384 350
385 - OLDDEP
351 + EXEC_DATA
352 + Executables that are not required to have non-executable writable
353 + data segments
386 354
387 - Objects that used to contain system functionality that
388 - has since migrated to libc. We preserve these
389 - libraries as pure filters for backward compatibility
390 - but nothing needs to link to them.
355 + EXEC_STACK
356 + Executables that are not required to have a non-executable stack
391 357
358 + NOCRLEALT
359 + Objects that should be skipped when building the alternative
360 + dependency mapping via the -d option.
392 361
393 - SKIP
362 + NODIRECT
363 + Directories and files that are allowed to have no direct bound
364 + symbols.
394 365
395 - Directories and/or individual objects to skip. Note
396 - that SKIP should be a last resort, used only when one
397 - of the other exceptions will not suffice.
366 + NOSYMSORT
367 + Files for which we skip checking of duplicate addresses in the
368 + symbol sort sections.
398 369
370 + OLDDEP Objects that used to contain system functionality that has since
371 + migrated to libc. We preserve these libraries as pure filters
372 + for backward compatibility but nothing needs to link to them.
399 373
400 - STAB
374 + SKIP Directories and/or individual objects to skip. Note that SKIP
375 + should be a last resort, used only when one of the other
376 + exceptions will not suffice.
401 377
402 - Objects that are allowed to contain debugging
403 - information (stabs).
378 + STAB Objects that are allowed to contain debugging information
379 + (stabs).
404 380
381 + TEXTREL
382 + Objects for which we allow relocations to the text segment.
405 383
406 - TEXTREL
384 + BUNDEF_OBJ
385 + Objects that are allowed to be unreferenced.
407 386
408 - Objects for which we allow relocations to the text
409 - segment.
387 + UNDEF_REF
388 + Objects that are allowed undefined references.
410 389
390 + UNUSED_DEPS
391 + Objects that are allowed to have unused dependencies.
411 392
412 - UNDEF_OBJ
393 + BUNUSED_OBJ
394 + Objects that are always allowed to be unused dependencies.
413 395
414 - Objects that are allowed to be unreferenced.
396 + UNUSED_RPATH
397 + Objects that are allowed to have unused runpath directories.
415 398
399 + FORBIDDEN
400 + Specifies that dependencies on a given object are forbidden.
416 401
417 - UNDEF_REF
418 -
419 - Objects that are allowed undefined references.
420 -
421 -
422 - UNUSED_DEPS
423 -
424 - Objects that are allowed to have unused dependencies.
425 -
426 -
427 - UNUSED_OBJ
428 -
429 - Objects that are always allowed to be unused
430 - dependencies.
431 -
432 -
433 - UNUSED_RPATH
434 -
435 - Objects that are allowed to have unused runpath
436 - directories.
437 -
402 + FORBIDDEN_DEP
403 + Specifies that a given object is permitted a forbidden
404 + dependency.
438 405
439 406 ALTERNATIVE DEPENDENCY MAPPING
440 - check_rtime was primarily designed to process a nightly builds $ROOT
441 - hierarchy. It is often the case that objects within this hierarchy must
442 - bind to dependencies within the same hierarchy to satisfy their
443 - requirements.
444 -
445 - To achieve this, check_rtime uses the shared objects specified with the
446 - -D or -d options. If neither option is specified, and the $CODEMGR_WS
447 - and $ROOT environment variables are defined, the proto area for the
448 - workspace is used. The objects found are used to create runtime
449 - configuration files via crle(1), that establish the new shared objects
450 - as alternatives to their underlying system location. check_rtime
451 - passes these configuration files as LD_CONFIG environment variable
452 - settings to ldd(1) using its -e option.
453 -
454 - The effect of these configuration files is that the execution of an
455 - object under ldd(1) will bind to the dependencies defined as
456 - alternatives. Simply put, an object inspected in the proto area will
457 - bind to its dependencies found in the proto area. Dependencies that
458 - have no alternative mapping will continue to bind to the underlying
459 - system.
407 + check_rtime was primarily designed to process a nightly builds $ROOT
408 + hierarchy. It is often the case that objects within this hierarchy must
409 + bind to dependencies within the same hierarchy to satisfy their
410 + requirements.
411 +
412 + To achieve this, check_rtime uses the shared objects specified with the
413 + -D or -d options. If neither option is specified, and the $CODEMGR_WS
414 + and $ROOT environment variables are defined, the proto area for the
415 + workspace is used. The objects found are used to create runtime
416 + configuration files via crle(1), that establish the new shared objects as
417 + alternatives to their underlying system location. check_rtime passes
418 + these configuration files as LD_CONFIG environment variable settings to
419 + ldd(1) using its --e option.
420 +
421 + The effect of these configuration files is that the execution of an
422 + object under ldd(1) will bind to the dependencies defined as
423 + alternatives. Simply put, an object inspected in the proto area will
424 + bind to its dependencies found in the proto area. Dependencies that have
425 + no alternative mapping will continue to bind to the underlying system.
460 426
461 427 ENVIRONMENT VARIABLES
462 - When the -D or -d option isn't in use, check_rtime uses the following
463 - environment variables to establish an alternative dependency mapping:
428 + When the -D or -d option isn't in use, check_rtime uses the following
429 + environment variables to establish an alternative dependency mapping:
464 430
465 - CODEMGR_WS
466 - The root of your workspace, which is the directory containing
467 - Codemgr_wsdata. Existence of this environment variable indicates
468 - that $ROOT should be investigated.
469 -
470 - ROOT
471 - Root of the proto area of your workspace. Any shared objects under
472 - this directory will be used to establish an alternative dependency
473 - mapping.
474 -
475 - If ldd(1) supports the -U option, it will be used to determine any
476 - unreferenced dependencies. Otherwise ldd(1) uses the older -u option
477 - which only detects unused references. If the following environment
478 - variable exists, and indicates an earlier release than 5.10 then ldd(1)
479 - also falls back to using the -u option.
431 + CODEMGR_WS
432 + The root of your workspace, which is the directory containing
433 + .git. Existence of this environment variable indicates that
434 + $ROOT should be investigated.
435 +
436 + ROOT Root of the proto area of your workspace. Any shared objects
437 + under this directory will be used to establish an alternative
438 + dependency mapping.
439 + If ldd(1) supports the -U option, it will be used to determine any
440 + unreferenced dependencies. Otherwise ldd(1) uses the older -u option
441 + which only detects unused references. If the following environment
442 + variable exists, and indicates an earlier release than 5.10 then ldd(1)
443 + also falls back to using the -u option.
480 444
481 - RELEASE
482 - The release version number of the environment being built.
445 + RELEASE
446 + The release version number of the environment being built.
483 447
484 448 ERROR CONDITIONS
485 - Inspection of an object with ldd(1) assumes it is compatible with the
486 - machine on which check_rtime is being run. Incompatible objects such
487 - as a 64-bit object encountered on a 32-bit system, or an i386 object
488 - encountered on a sparc system, can not be fully inspected. These
489 - objects are displayed as:
449 + Inspection of an object with ldd(1) assumes it is compatible with the
450 + machine on which check_rtime is being run. Incompatible objects such as
451 + a 64-bit object encountered on a 32-bit system, or an i386 object
452 + encountered on a sparc system, can not be fully inspected. These objects
453 + are displayed as:
490 454
491 455 foo: has wrong class or data encoding
492 456
493 457 FILES
494 - $CODEMGR_WS/exception_list/check_rtime
495 - /opt/onbld/etc/exception_list/check_rtime
496 -
497 -SEE ALSO
498 - crle(1), elfdump(1), find_elf(1ONBLD), ldd(1), ld.so.1(1), mcs(1).
458 + $CODEMGR_WS/exception_list/check_rtime
499 459
460 + /opt/onbld/etc/exception_list/check_rtime
500 461
462 +SEE ALSO
463 + crle(1), elfdump(1), ld.so.1(1), ldd(1), mcs(1), find_elf(1ONBLD)
501 464
502 - March 9, 2010 CHECK_RTIME(1ONBLD)
465 +illumos February 19, 2018 illumos
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX