1appcert(1) User Commands appcert(1)
2
6 appcert - examine application-level products for unstable use of
7 Solaris interfaces
8
10 appcert [-h] [-n] [-f infile] [-w working_dir] [-B] [-L]
11 [-S] {obj | dir}...
12
15 The appcert utility examines an application's conformance to the
16 Solaris Application Binary Interface (ABI). The Solaris ABI defines the
17 runtime library interfaces in Solaris that are safe and stable for
18 application use. More specifically, appcert identifies any dependencies
19 on unstable runtime interfaces, as well as certain other risks that
20 could cause the product to fail to work on a subsequent release of
21 Solaris.
22 appcert checks for:
25 o Private symbol usage in Solaris libraries. These are pri‐
27 vate symbols, that is, functions or data, that are not
28 intended for developer consumption. They are interfaces that
29 Solaris libraries use to call one another. These symbols
30 might change their semantic behavior or even disappear alto‐
31 gether (so-called demoted symbols), so it is a good prac‐
32 tice to make sure your application does not depend upon any
33 of them.
34 o Static linking. In particular, this refers to static linking
36 of archives libc.a, libsocket.a, and libnsl.a, that is,
37 instead of dynamically linking the corresponding shared
38 object .so's. Because the semantics of private symbol calls
39 from one Solaris library to another can change from one
40 release to another, it is not a good practice to hardwire
41 library code into your binary objects.
42 o Unbound symbols. These are library symbols (that is, func‐
44 tions or data) that the dynamic linker could not resolve
45 when appcert was run. This might be an environment problem
46 (for example, LD_LIBRARY_PATH) or a build problem (for exam‐
47 ple, not specifying -llib and/or -z defs with compiling).
48 They are flagged to point these problems out and in case a
49 more serious problem is indicated.
50 An entire product can be readily examined by appcert (that is, if the
53 product is a collection of many programs and supporting shared objects)
54 by referring appcert to the directories where the product is installed.
55 To perform its task, appcert constructs a profile of interface depen‐
58 dencies for each object file within the product (whether an executable
59 object or shared object), to determine all the Solaris system inter‐
60 faces that are depended upon. (Notice that appcert uses the Solaris
61 runtime linker to make this determination.) These dependency profiles
62 are then compared to a definition of the Solaris ABI to identify any
63 interfaces that are Private (unsafe and unstable for application-level
64 use).
65 appcert generates a simple roll-up report that indicates which of the
68 product's components, if any, had liabilities and what those liabili‐
69 ties were. The report aids developers who are examining their product's
70 release-to-release stability.
71 Notice that appcert produces complete interface dependency information,
74 both the Public (safe and stable) Solaris interfaces and the Private
75 (non-ABI) interfaces. This information can also be examined for each
76 product component, if you want.
77 IMPORTANT: appcert must run in the same environment in which the appli‐
80 cation being checked runs. See NOTES.
81
83 The following options are supported:
84 -B If appcert is run in batch mode, the output report
86 will contain one line per binary, beginning with PASS
87 if no problems were detected for the binary, FAIL if
88 any problems were found, or INC if the binary could
89 not be completely checked. Do not interpret these
90 labels too literally. For example, PASS just means
91 that none of the appcert warnings were triggered.
92 These strings are flush left and so can be selected
93 via grep ^FAIL ..., and so forth.
94 -f infile Specifies the file infile that contains a list of
97 files (one per line) to check. This list is appended
98 to the list determined from the command line operands
99 (see OPERANDS below).
100 -h Prints out the usage information.
103 -L appcert examines your product for the presence of
106 shared objects. If it finds some, it appends the
107 directories they reside in to LD_LIBRARY_PATH. Use
108 this flag to prevent appcert from doing this.
109 -n When searching directories for binaries to check,
112 this option does not follow symbolic links. See
113 find(1).
114 -S Appends Solaris library directories (that is,
117 /usr/openwin/lib:/usr/dt/lib) to LD_LIBRARY_PATH.
118 -w working_dir Identifies the directory in which to run the library
121 components and create temporary files (default is
122 /tmp).
123
126 The following operands are supported:
127 {obj | dir} ... A complete list of objects and/or directories that
129 contain the objects constituting the product to be
130 checked. appcert recursively searches directories
131 looking for object files; non-object files are
132 ignored.
133
136 The following exit values are returned:
137 0 appcert ran successfully and found no potential binary stability
139 problems.
140 1 appcert failed to run successfully.
143 2 Some of the objects checked have potential binary stability prob‐
146 lems.
147 3 No binary objects were located that could be checked.
150
153 If the object file to be examined depends on libraries, those dependen‐
154 cies must be recorded in it (by using the compiler's -l switch).
155 If the object file to be examined depends on other shared libraries,
158 those libraries must be accessible via LD_LIBRARY_PATH or RUNPATH when
159 appcert is run.
160 To check 64-bit applications, the machine must be running the 64-bit
163 Solaris kernel. See isalist(1). Also, the checks for static linking are
164 currently not done on 64-bit applications.
165 appcert cannot examine:
168 o Object files that are completely or partially statically
170 linked.
171 Completely statically linked objects are reported as
172 unstable.
173 o Executable files that do not have execute permission set.
175 These are skipped. Shared objects without execute permis‐
176 sion are not skipped.
177 o Object files that are setuid root.
179 Due to limitations in ldd(1), these are skipped. Copy
180 and/or change the permissions to check them.
181 o Non-ELF file executables such as shell scripts.
183 o Non-C language interfaces to Solaris; for example, C++ and
185 Java.
186 The code itself need not be in C as long as the calls to
187 Solaris libaries are in C.
188
190 appcert records its findings in the following files in the working
191 directory (/tmp/appcert.????? by default):
192 Index A mapping between checked binaries and the subdirectory in
194 the working directory in which the output specific to that
195 binary can be found.
196 Report A copy of the rollup report that was displayed on stdout
199 when appcert was run.
200 Skipped A list of binaries that appcert was asked to check but had
203 to skip, along with a brief reason why each was skipped.
204 In addition, there is per-object information in the subdirectories
208 under appcert.?????/objects/, in the following files:
209 check.demoted_symbols A list of symbols suspected to be demoted
211 Solaris symbols.
212 check.dynamic.private A list of private Solaris symbols to which the
215 object makes direct bindings.
216 check.dynamic.public A list of public Solaris symbols to which the
219 object makes direct bindings.
220 check.dynamic.unbound A list of symbols not bound by the dynamic
223 linker when ldd -r was run. For convenience,
224 ldd output lines containing file not found are
225 also included.
226 summary.dynamic A pretty-printed summary of dynamic bindings
229 for the objects examined, including tables of
230 Public and Private symbols used from each
231 Solaris library.
232 Other files are temporary files used internally by appcert.
236
238 Private Symbol Use
239 Private symbols are functions or data variables in a Solaris library
240 that are not intended for developer or external use. These symbols are
241 interfaces that the Solaris libraries use to call and communicate with
242 one another. They are marked in pvs(1) output with the symbol version
243 name SUNWprivate.
244 Private symbols can change their semantic behavior or even disappear
247 altogether (demoted or deprecated symbols), so your application should
248 not depend upon any of them.
249 Demoted Symbols
251 Demoted symbols are functions or data variables in a Solaris library
252 that were once private to that library and have been removed (or possi‐
253 bly scoped local to the library) in a later Solaris release. If your
254 application directly calls one of these demoted symbols, it will fail
255 to run (relocation error) on the release in which the symbol was
256 removed and releases thereafter.
257 In some rare cases, a demoted symbol will return in a later release,
260 but nevertheless there are still some releases on which the application
261 will not run.
262 Sun Microsystems Inc. performed most of the library scoping in the
265 transition from Solaris 2.5.1 to 2.6. This action was done to increase
266 binary stability. By making these completely internal interfaces invis‐
267 ible (that is, they cannot be dynamically linked against), a developer
268 cannot accidentally or intentionally call these interfaces. For more
269 information, see the Linker and Libraries Guide, in particular the
270 chapter on versioning. This document may be found online at
271 http://docs.sun.com.
272 Unbound Symbols
274 Unbound symbols are library symbols (that is, functions or data) refer‐
275 enced by the application that the dynamic linker could not resolve when
276 appcert was run. Note: appcert does not actually run your application,
277 so some aspect of the environment that affects dynamic linking might
278 not be set properly.
279 Unbound symbols do not necessarily indicate a potential binary stabil‐
282 ity problem. They only mean that when appcert was run, the runtime
283 dynamic linker could not resolve these symbols.
284 Unbound symbols might be due to LD_LIBRARY_PATH not being correctly
287 set. Make sure it is set, so that all of your binary objects can find
288 all of the libraries they depend on (either your product's own
289 libraries, Solaris libraries, or those of a third party). Then re-run
290 appcert.
291 You might find it useful to write a shell script that sets up the envi‐
294 ronment correctly and then runs appcert on the binaries you want to
295 check.
296 Another common cause for unbound symbols is when a shared object under
299 test has not recorded its dynamic dependencies, that is, at build time
300 the -l switch was not supplied to the compiler and ld(1). So the shared
301 object requires that the executables that link against it have the cor‐
302 rect dependencies recorded.
303 Notice that such a shared object can either be linked in the standard
306 way (that is, specified at an executable's build time) or dynamically
307 opened (for example, an executable calls dlopen(3C) on the shared
308 object sometimes when running). Either case can give rise to unbound
309 symbols when appcert is run. The former can usually be resolved by set‐
310 ting LD_LIBRARY_PATH appropriately before running appcert. The latter
311 (dlopen) is usually difficult to resolve. Under some circumstances, you
312 might be able to set LD_PRELOAD appropriately to preload the needed
313 libraries, but this procedure does not always work.
314 How do you know if the environment has been set up correctly so that
317 there will be no unbound symbols? It must be set up so that running ldd
318 -r on the binary yields no "file not found" or "symbol not found"
319 errors. See ld.so.1(1) and ldd(1) for more information on dynamic link‐
320 ing.
321 In any event, appcert flags unbound symbols as a warning in case they
324 might indicate a more serious problem. Unbound symbols can be an indi‐
325 cator of dependencies on demoted symbols (symbols that have been
326 removed from a library or scoped local to it). Dependencies on demoted
327 symbols will lead to serious binary stability problems.
328 However, setting up the environment properly should remove most unbound
331 symbols. In general, it is good practice to record library dependencies
332 at build time whenever possible because it helps make the binary object
333 better defined and self-contained. Also recommended is using the -z
334 defs flag when building shared objects, to force the resolution of all
335 symbols during compilation. See ld(1) for more information.
336 No Bindings Found
338 appcert runs /bin/ldd -r on each binary object to be tested. It sets
339 the environment variable LD_DEBUG="files,bindings". (See ldd(1) and
340 ld.so.1(1) for more information). If that command fails for some rea‐
341 son, appcert will have no dynamic symbol binding information and will
342 find "no bindings".
343 appcert can fail if any of the following is true:
346 o The binary object does not have read permission.
348 o The binary object is SUID or SGID and the user does not have
350 sufficient privileges.
351 o The binary object is an executable without the execute per‐
353 mission bit set.
354 o The binary object is completely statically linked.
356 o The binary object has no library dependency information
358 recorded.
359 Other cases exist as well (for example, out of memory). In general,
362 this flag means that appcert could not completely examine the object
363 due to permissions or environment. Try to modify the permissions or
364 environment so that the dynamic bindings can be recorded.
365 Obsolete Library
367 An obsolete library is one whose use is deprecated and that might, in
368 some future release, be removed from Solaris altogether. appcert flags
369 these because applications depending on them might not run in future
370 releases of Solaris. All interfaces, including Private ones, in an
371 obsolete library are frozen and will not change.
372 Use of sys_errlist/sys_nerr
374 Direct use of the symbols sys_errlist or sys_nerr presents a risk in
375 which reference might be made past the end of the sys_errlist array.
376 These symbols are deprecated in 32-bit versions of Solaris and are
377 absent altogether in 64-bit versions. Use strerror(3C) instead.
378 Use of Strong vs. Weak Symbols
380 The "strong" symbols (for example, _socket) associated with "weak" sym‐
381 bols (for example, socket ) are reserved as private (their behavior
382 could change in the future). Your application should only directly ref‐
383 erence the weak symbol (usually the strong symbols begin with "_").
384 Note: Under certain build environments, the strong/private symbol
387 dependency gets recorded into your binary instead of the weak/public
388 one, even though the source code doesn't appear to reference the pri‐
389 vate symbol. Nevertheless, steps should be taken to trace down why this
390 is occurring and fix the dependency.
391
393 appcert needs to run in the same environment in which the application
394 being checked runs. Otherwise it might not be able to resolve refer‐
395 ences correctly to interfaces in the Solaris libraries. Take the fol‐
396 lowing steps:
397 1. Make sure that LD_LIBRARY_PATH and any other aspects of the
399 environment are set to whatever settings are used when the
400 application is run. Also make sure that it contains the
401 directories containing any non-Solaris shared objects that
402 are part of the product, so that they can be found when ref‐
403 erenced.
404 2. Make sure that all the binaries to be checked:
406 o Are dynamically linked ELF objects
408 o Have execute permission set on executables (this is not
410 necessary for shared objects)
411 o Are not SUID root (otherwise you will have to be root to
413 check them; make non-SUID copies and check those if nec‐
414 essary).
415 You might find it useful to write a shell script that sets up the envi‐
418 ronment correctly and then runs appcert.
419 Some potential problems that can be encountered are:
422 o appcert reports unbound symbols that appear to be part of
424 Solaris libraries.
425 This is probably caused when the application uses dlopen(3C)
427 to access a shared object that does not have its Solaris
428 dependencies recorded. appcert cannot resolve symbol use in
429 such cases, since the dynamic linker is never invoked on the
430 shared object, and there is no other dependency information
431 that could be used to resolve the Solaris symbol bindings.
432 This can also occur with non-Solaris symbols.
433 To avoid this problem, make sure that when a shared object
435 is built, its dependencies on Solaris libraries are explic‐
436 itly recorded by using the -llib option on the compile line
437 (see cc(1) and ld(1)).
438 o appcert reports that the application uses a Solaris private
440 symbol that is not referenced in the application's source
441 code.
442 This problem is most likely due to static linking of a
444 Solaris library that references that symbol. Since appcert
445 uses the dynamic linker to resolve symbols, statically
446 linked libraries appear to appcert to be part of the appli‐
447 cation code (which, in a sense, they are). This can also
448 sometimes happen as a result of macro substitution in a
449 Solaris header file.
450 To avoid this problem, whenever possible do not statically
452 link Solaris library archives into your application.
453 o appcert does not recognize a library as part of Solaris.
455 Some obsolete Solaris libraries are so old that they were
457 obsoleted before their symbols could be versioned. Conse‐
458 quently, appcert cannot recognize them as being part of
459 Solaris.
460
462 The use of the terms "public" and "private" as equivalent to "stable"
463 and "unstable" is unfortunately somewhat confusing. In particular,
464 experimental or evolving interfaces are public in the sense that they
465 are documented and their use is encouraged. But they are unstable,
466 because an application built with them might not run on subsequent
467 releases. Thus, they are classified as private for appcert's purposes
468 until they are no longer evolving. Conversely, obsolete interfaces will
469 eventually disappear, and so are unstable, even though they have been
470 public and stable in the past and are still treated as public by
471 appcert. Fortunately, these two situations are rare.
472
474 See attributes(5) for descriptions of the following attributes:
475 ┌─────────────────────────────┬─────────────────────────────┐
480 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
481 ├─────────────────────────────┼─────────────────────────────┤
482 │Availability │SUNWapct │
483 ├─────────────────────────────┼─────────────────────────────┤
484 │Interface stability │Stable │
485 └─────────────────────────────┴─────────────────────────────┘
486
488 cc(1), find(1), isalist(1), ld(1), ldd(1), ld.so.1(1), pvs(1),
489 dlopen(3C), strerror(3C), Intro(4), attributes(5)
490SunOS 5.11 29 Jan 2007 appcert(1)