appcert Utility
The appcert utility is a Perl script that statically examines ELF binaries (executables and shared objects) and compares the library symbols used against a model of public/private interfaces in a given Solaris release. The utility runs on either SPARC or Intel platforms, and can check interface usage for both SPARC and Intel 32-bit interfaces as well as the 64-bit interfaces on SPARC. Note that appcert only examines C language interfaces.
As new Solaris releases become available, some library interfaces might change their behavior or disappear entirely, affecting the performance of applications reliant on those interfaces. The Solaris ABI defines runtime library interfaces that are safe and stable for application use. The appcert utility is designed to help developers verify an application's compliance with the Solaris ABI.
What appcert Checks
The appcert utility examines your applications for:
Private symbol usage
Static linking
Unbound symbols
Private Symbol Usage
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.
Static Linking
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.
Unbound Symbols
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.
What appcert Does Not Check
If 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.
Working with appcert
To check your application with appcert, type:
appcert object|directory |
replacing object|directory with either:
The complete list of objects you want appcert to examine
The complete list of directories that contain such objects
Note - 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, usually the screen. A copy of this report is written in the working directory, which is usually /tmp/appcert.pid, 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 Options
The 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.
| -B | 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. |
| -f infile | 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. |
| -h | Prints usage information for appcert. |
| -L | By default, appcert notes any shared objects in an application and appends the directories in which they reside to LD_LIBRARY_PATH. The -L switch disables this behavior. |
| -n | By default, appcert follows symbolic links when it searches directories for binaries to check. The -n switch disables this behavior. |
| -S | Appends the Solaris library directories /usr/openwin/lib and /usr/dt/lib to LD_LIBRARY_PATH. |
| -w working_dir | 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. |
Using appcert for Application Triage
The appcert utility can be used to quickly and easily discern which applications in a given set have potential stability problems. If appcert does not report any stability problems, the application is not likely to encounter binary stability problems in subsequent Solaris releases. The following table lists some common binary stability problems.
Table 10-1 Common Binary Stability Problems
Problem | Course of Action |
|---|---|
Use of a private symbol that is known to change | Eliminate use of symbol immediately. |
Use of a private symbol that has not changed yet | Application can still be run for now, but eliminate use of symbol as soon as practical. |
Static linking of a library with a shared object counterpart | Use shared object counterpart instead. |
Static linking of a library with no shared object counterpart | Convert .a file to .so file by using the command ld -z allextract if possible. Otherwise, continue to use static library until shared object is available. |
Use of a private symbol for which no public equivalent is available | Contact Sun and request a public interface. |
Use of a symbol that is deprecated or planned for removal | Application can still be run for now, but eliminate use of symbol as soon as practical. |
Use of a public symbol that has changed | Recompile. |
Potential stability problems caused by the use of private interfaces may not occur on a given release, because the behavior of private interfaces does not always change between releases. To verify that a private interface's behavior has changed in the target release, use the apptrace tool. Usage of apptrace is discussed in "Using apptrace for Application Verification".