appcert
appcert is new in the Solaris 4/01 release. For more information see, System Interface Guide.
This chapter discusses:
Purpose of the appcert
utility
Running and using appcert
Correcting problems appcert
reports
Writing appcert
-compliant code
For the most current man pages, use the man command. The Solaris 8 Update release man pages include new feature information that is not in the Solaris 8 Reference Manual Collection.
appcert
UtilityAs new Solaris releases become available, some library interfaces might
change their behavior or disappear entirely. Applications that rely on those
interfaces would then stop functioning. The Solaris Application Binary Interface
(ABI) defines runtime library interfaces that are safe and stable for application
use. Applications that are written to conform with the Solaris ABI will remain
stable under future releases of Solaris. The appcert
utility is designed to help
developers verify an application's compliance with the Solaris ABI.
appcert
ChecksThe appcert
utility examines your applications for:
Private symbol usage
Static linking
Unbound symbols
Private symbols are functions or data that is used by Solaris libraries to call one another. The semantic behavior of private symbols might change, and symbols may sometimes be removed (such symbols are called demoted symbols.) The mutable nature of private symbols introduces the potential for instability in applications that depend on them.
Because the semantics of private symbol calls from one Solaris library to another might change between releases, the creation of static links to archives degrades the binary stability of an application. Dynamic links to the archive's corresponding shared object file avoid this problem.
The appcert
utility uses the dynamic linker to resolve the library symbols
that are used by the application being examined. Symbols the dynamic linker
cannot resolve are called unbound symbols. Unbound symbols
might be caused by environment problems, such as an incorrectly set LD_LIBRARY_PATH variable, or build problems, such as omitting the
definitions of the -llib or -z switches at compile time. While these examples are minor, unbound
symbols that are reported by appcert
might indicate a more serious problem.
appcert
Does Not CheckIf the object file you want appcert
to examine depends on libraries, those
dependencies must be recorded in the object. To do so, be sure to use the
compiler's -l switch when compiling the code. If the object
file depends on other shared libraries, those libraries must be accessible
through LD_LIBRARY_PATH or RPATH at
the time you run appcert
.
The appcert
application cannot check 64–bit applications unless the
machine is running the 64–bit Solaris kernel. Static linking checks
are not performed by appcert
when it is checking 64–bit applications.
The appcert
utility cannot examine:
Object files that are completely or partially statically linked. A completely statically linked object is reported as unstable.
Executable files that do not have the execute permission set.
The appcert
utility skips such executables. Shared objects without the execute
permission set are examined normally.
Object files whose user ID is set to root.
Non-ELF executables, such as shell scripts.
Solaris interfaces in languages other than C. The code itself need not be in C, but the call to the Solaris library must be.
appcert
To check your application with appcert
, type:
appcert object|directory |
The complete list of objects you want appcert
to examine and/or
The complete list of directories that contain such objects.
If appcert
is run in an environment different from the one in which
the application being checked would be run, the utility may not be able to
resolve references to Solaris library interfaces correctly.
The appcert
utility uses the Solaris runtime linker to construct a profile
of interface dependencies for each executable or shared object file. This
profile is used to determine the Solaris system interfaces upon which the
application depends. The dependencies outlined in the profile are compared
to the Solaris ABI to verify conformance (no private interfaces should be
found).
The appcert
utility recursively searches directories for object files, ignoring
non-ELF object files. After appcert
has finished checking the application, it
prints a rollup report to the standard output (stdout,
usually the screen). A copy of this report is written in the working directory,
which is usually /tmp/appcert.pid/Report, in a file named Report. In the subdirectory
name, pid represents the 1– to 6–digit process
ID of that particular instantiation of appcert
. See appcert
Results
for more on the directory structure to which appcert
writes output files.
appcert
OptionsThe following options modify the behavior of the appcert
utility. You can
type any of these options at the command line, after the appcert command but before the object|directory
operand.
Runs appcert
in batch mode.
In batch mode, the report produced by appcert
will contain one line for
each binary checked.
A line that begins with PASS indicates the binary named in that line
did not trigger any appcert
warnings.
A line that begins with FAIL indicates problems were found in that binary.
A line that begins with INC indicates the binary named in that line could not be completely checked.
The file infile should contain a list of files to check, with one file name per line. These files are added to any files already specified at the command line. If you use this switch, you do not need to specify an object or directory at the command line.
Prints usage
information for appcert
.
By default, appcert
notes any shared objects in an application and appends the directories they
reside in to LD_LIBRARY_PATH. The -L
switch disables this behavior.
By default, appcert
follows symbolic links when it searches directories for binaries to check.
The -n switch disables this behavior.
Appends the Solaris library directories /usr/openwin/lib and /usr/dt/lib to LD_LIBRARY_PATH.
Specifies a directory in which to run the library components
and create temporary files. If this switch is not specified, appcert
uses the /tmp directory.
appcert
ResultsThe results of the appcert
utility's analysis of an application's object
files are written to several files that are located in the appcert
utility's working
directory (typically /tmp) The main subdirectory under
the working directory is appcert
.pid,
where pid is the process ID for that instantiation
of appcert
.
Contains the mapping between checked binaries and the subdirectory
in which appcert
output specific to that binary is located.
Contains
a copy of the rollup report displayed on stdout when appcert
is run.
Contains
a list of binaries that appcert
was asked to check but was forced to skip, along
with the reason each binary was skipped. These reasons are:
File is not a binary object
File cannot be read by the user
File contains metacharacters
File does not have the execute bit set
A separate subdirectory is under the objects
subdirectory for each object examined by appcert
. Each of these subdirectories
contains the following files:
check.demoted.symbols | ||
Contains
a list of symbols |
||
check.dynamic.private | ||
Contains a list of private Solaris symbols to which the object is directly bound. |
||
check.dynamic.public | ||
Contains a list of public Solaris symbols to which the object is directly bound. |
||
check.dynamic.unbound | ||
Contains a list of symbols not bound by the dynamic linker when running ldd -r. Lines returned by ldd containing “file not found” are also included. |
||
summary.dynamic | ||
Contains
a printer-formatted summary of dynamic bindings in the objects |
When appcert
exits, it returns one of four exit values.
No potential sources
of binary instability were found by appcert
.
The appcert
utility did not run successfully.
Some of the objects checked by appcert
have potential binary stability problems.
The appcert
utility did not find any
binary objects to check.
appcert
Private Symbol Use. Because private symbols
might change their behavior or disappear from one Solaris release to another,
an application that depends on private symbols might not run on a Solaris
release different from the one it was developed in. If appcert
reports private
symbol usage in your application, rewrite the application to avoid the use
of private symbols.
Demoted Symbols. Demoted symbols are functions or data variables in a Solaris library that have been removed or scoped locally in a later Solaris release. An application that directly calls such a symbol will fail to run on a release whose libraries do not export that symbol.
Unbound Symbols. Unbound symbols are
library symbols that are referenced by the application that the dynamic linker
was unable to resolve when called by appcert
. While unbound symbols are not always
an indicator of poor binary stability, they might indicate a more serious
problem, such as dependencies on demoted symbols.
Obsolete Library. An obsolete library
might be removed from Solaris in a future release. The appcert
utility flags any
use of such a library, because applications that depend on them will not function
in a future release that does not feature the library. To avoid this problem,
do not use interfaces from obsolete libraries.
Use of sys_errlist or sys_nerr. The use of the sys_errlist and sys_nerr symbols might degrade binary stability, as a reference might be made past the end of the sys_errlist array. To avoid this risk, use strerror instead.
Use of strong and weak symbols. The strong symbols that are associated with weak symbols are reserved as private because their behavior might change in future releases of Solaris. Applications should only directly reference weak symbols. An example of a strong symbol is _socket, which is associated with the weak symbol socket.