Print this page
9139 check_rtime should be able to forbid libraries
9140 check_rtime should learn libnsl is safe now
9141 check_rtime exceptions could be cleaner
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/tools/scripts/check_rtime.1onbld
+++ new/usr/src/tools/scripts/check_rtime.1onbld
1 1 .\" Copyright (c) 2001, 2010, Oracle and/or its affiliates. All rights reserved.
2 2 .\"
3 3 .\" CDDL HEADER START
4 4 .\"
5 5 .\" The contents of this file are subject to the terms of the
6 6 .\" Common Development and Distribution License (the "License").
7 7 .\" You may not use this file except in compliance with the License.
8 8 .\"
9 9 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
10 10 .\" or http://www.opensolaris.org/os/licensing.
11 11 .\" See the License for the specific language governing permissions
|
↓ open down ↓ |
11 lines elided |
↑ open up ↑ |
12 12 .\" and limitations under the License.
13 13 .\"
14 14 .\" When distributing Covered Code, include this CDDL HEADER in each
15 15 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
16 16 .\" If applicable, add the following below this CDDL HEADER, with the
17 17 .\" fields enclosed by brackets "[]" replaced with your own identifying
18 18 .\" information: Portions Copyright [yyyy] [name of copyright owner]
19 19 .\"
20 20 .\" CDDL HEADER END
21 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
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
31 40 attempts to check a number of ELF runtime attributes
32 41 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
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
43 64 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
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
49 76 option, or the existence of the environment variables
50 -\fB$CODEMGR_WS/$ROOT\fP instruct
51 -.I check_rtime
77 +.Ev $CODEMGR_WS
78 +or
79 +.Ev $ROOT
80 +instruct
81 +.Nm check_rtime
52 82 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
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
62 95 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
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
81 118 Unsatisfied symbol relocations indicate that some thread of
82 119 execution through the object will fail when it is unable to
83 120 locate a referenced symbol.
84 -.sp
121 +.Pp
85 122 A missing, or mismatched version of a dependency is the typical
86 123 reason for unsatisfied symbol relocations (see missing dependency
87 124 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
125 +.Pp
126 +.Dl foo: symbol not found: bar <no -zdefs?>
127 +.Pp
94 128 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
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
101 142 will report these symbols as undefined.
102 -.RE
103 -.TP
104 -\(bu
143 +.It
105 144 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
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
120 159 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
160 +to the extent of unused dependencies.
161 +They also result in unnecessary processing at link-edit time.
162 +.Pp
124 163 Unreferenced dependency removal guards against a dependency becoming
125 164 unused when combined with
126 165 different objects, or as the other object dependencies evolve.
127 166 Unreferenced dependencies are displayed as:
128 -.sp
129 -.RS 6
167 +.Bd -literal
130 168 foo: unreferenced object=bar.so.1; \\
131 -.br
132 169 unused dependency of libfoo.so.1 \\
133 -.br
134 170 <remove lib or -zignore?>
135 -.RE
136 -.RS 4
137 -.sp
138 -See also the section ENVIRONMENT VARIABLES.
139 -.RE
140 -.TP
141 -\(bu
171 +.Ed
172 +.Pp
173 +See also the section
174 +.Sx ENVIRONMENT VARIABLES .
175 +.It
142 176 Unused search paths are wasteful at runtime.
143 177 Unused search paths are displayed as:
144 -.sp
145 -.RS 6
178 +.Bd -literal
146 179 foo: unused search path=/usr/foo/lib \\
147 -.br
148 180 (RUNPATH/RPATH from file libfoo.so.1) \\
149 -.br
150 181 <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.
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.
159 192 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
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
213 258 foo: debugging sections should be deleted \\
214 -.br
215 259 <no strip -x?>
216 -.RE
217 -.TP
218 -\(bu
219 -All objects should retain their full \fI.symtab\fP symbol table.
260 +.Ed
261 +.It
262 +All objects should retain their full
263 +.Em .symtab
264 +symbol table.
220 265 Although this consumes disk space, it provides for more extensive stack
221 266 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.
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.
226 274 Objects that do not contain a symbol table are displayed as:
227 -.sp
228 -.RS 6
275 +.Bd -literal
229 276 foo.so.1: symbol table should not be stripped \\
230 -.br
231 277 <remove -s?>
232 -.RE
233 -.TP
234 -\(bu
278 +.Ed
279 +.It
235 280 Applications should have a non-executable stack defined to make
236 281 them less vulnerable to buffer overflow attacks.
237 -.sp
238 -Not inheriting the \fB$(LDFLAGS)\fP macro in \fIcmd/Makefile.cmd\fP
282 +.Pp
283 +Not inheriting the
284 +.Dv $(LDFLAGS)
285 +macro in
286 +.Pa cmd/Makefile.cmd
239 287 is the typical reason for not having a non-executable stack definition.
240 288 Applications without this definition are displayed as:
241 -.sp
242 -.RS 6
289 +.Bd -literal
243 290 foo: application requires non-executable stack \\
244 -.br
245 -.nf
246 291 <no -Mmapfile_noexstk?>
247 -.fi
248 -.RE
249 -.sp
250 -.TP
251 -\(bu
292 +.Ed
293 +.It
252 294 x86 applications should have a non-executable data segment defined to make
253 295 them less vulnerable to buffer overflow attacks.
254 -.sp
255 -Not inheriting the \fB$(LDFLAGS)\fP macro in \fIcmd/Makefile.cmd\fP
296 +.Pp
297 +Not inheriting the
298 +.Dv $(LDFLAGS)
299 +macro in
300 +.Pa cmd/Makefile.cmd
256 301 is the typical reason for not having a non-executable data definition.
257 302 Applications without this definition are displayed as:
258 -.sp
259 -.RS 6
303 +.Bd -literal
260 304 foo: application requires non-executable data \\
261 -.br
262 -.nf
263 305 <no -Mmapfile_noexdata?>
264 -.fi
265 -.RE
266 -.sp
267 -.TP
268 -\(bu
306 +.Ed
307 +.It
269 308 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
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
276 318 enforces the rule that only one symbol can appear in the sort sections for
277 319 any given address.
278 320 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
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
287 332 Duplicate entries in a symbol sort section are
288 333 displayed in one of the following ways, depending on
289 334 whether the section is for regular or thread-local symbols:
290 -.sp
291 -.RS 6
335 +.Bd -literal
292 336 foo: .SUNW_dynsymsort: duplicate ADDRESS: sym1, sym2
293 -.br
294 337 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
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
310 356 foo: object has no direct bindings \\
311 -.br
312 -.nf
313 357 <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.
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.
322 368 This doesn't necessarily indicate an error condition, but
323 369 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
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
336 383 Needed dependencies are printed for any dynamic object.
337 384 In the freeware world this often helps the introducer of a new
338 385 shared object discover that an existing binary has become its
339 386 consumer, and thus that binaries package dependencies may require updating.
340 387 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.
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.
349 405 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.
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.
364 425 Each symbol defined by the object is shown along with the version it belongs to.
365 426 Changes to the symbols defined by an object, or the versions they belong to,
366 427 do not necessarily indicate an error condition, but
367 428 provides information that is often useful for gatekeepers to track
368 429 changes in a release.
369 -.sp
370 -.SH OPTIONS
371 -.LP
430 +.Sh OPTIONS
372 431 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
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
390 462 An exception file is used to exclude objects from
391 -the usual rules. See EXCEPTION FILE FORMAT.
392 -.TP
393 -.B \-f listfile
463 +the usual rules.
464 +See
465 +.Sx EXCEPTION FILE FORMAT .
466 +.It Fl f Ar listfile
394 467 Normally,
395 -.I interface_check
468 +.Ic interface_check
396 469 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
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
414 493 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
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
428 510 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
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
437 523 will use
438 -.I /opt/onbld/etc/exception_list/check_rtime
524 +.Pa /opt/onbld/etc/exception_list/check_rtime
439 525 as a fallback default exception file.
440 -.P
526 +.Pp
441 527 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
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
450 542 regular expression:
451 -.sp
452 -.in +4
453 -.nf
454 -keyword perl-regex
455 -.fi
456 -.in -4
457 -.sp
543 +.Pp
544 +.Dl keyword perl-regex
545 +.Pp
458 546 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.
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
461 553 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
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
475 566 The exceptions understood by
476 -.I check_rtime
567 +.Nm check_rtime
477 568 are:
478 -.sp
479 -.ne 2
480 -.na
481 -\fBEXEC_DATA\fR
482 -.ad
483 -.RS 17n
484 -.sp
569 +.Bl -tag -width indent
570 +.It EXEC_DATA
485 571 Executables that are not required to have non-executable writable
486 572 data segments
487 -.RE
488 -
489 -.sp
490 -.ne 2
491 -.na
492 -\fBEXEC_STACK\fR
493 -.ad
494 -.RS 17n
495 -.sp
573 +.It EXEC_STACK
496 574 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
575 +.It NOCRLEALT
506 576 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
577 +mapping via the
578 +.Fl d
579 +option.
580 +.It NODIRECT
517 581 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
582 +.It NOSYMSORT
527 583 Files for which we skip checking of duplicate addresses in the
528 584 symbol sort sections.
529 -.RE
530 -
531 -.sp
532 -.ne 2
533 -.na
534 -\fBOLDDEP\fR
535 -.ad
536 -.RS 17n
537 -.sp
585 +.It OLDDEP
538 586 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
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
561 595 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
596 +.It TEXTREL
571 597 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
598 +.It BUNDEF_OBJ
581 599 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
600 +.It UNDEF_REF
591 601 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
602 +.It UNUSED_DEPS
601 603 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
604 +.It BUNUSED_OBJ
611 605 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
606 +.It UNUSED_RPATH
621 607 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
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
631 621 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
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
643 647 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
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
653 665 uses the following environment variables to
654 666 establish an alternative dependency mapping:
655 -.LP
656 -.B CODEMGR_WS
657 -.RS 4
667 +.Bl -tag -width indent
668 +.It Ev CODEMGR_WS
658 669 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
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
678 700 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).
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
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX