The appcert utility examines an application's conformance to the Solaris Application Binary Interface (ABI). The Solaris ABI defines the runtime library interfaces in Solaris that are safe and stable for application use. More specifically, appcert identifies any dependencies on unstable runtime interfaces, as well as certain other risks that could cause the product to fail to work on a subsequent release of Solaris.

appcert checks for:

• Private symbol usage in Solaris libraries. These are private symbols, that is, functions or data, that are not intended for developer consumption. They are interfaces that Solaris libraries use to call one another. These symbols might change their semantic behavior or even disappear altogether (so-called "demoted" symbols), so it is a good practice to make sure your application does not depend upon any of them.
• Static linking. In particular, this refers to static linking of archives libc.a, libsocket.a, and libnsl.a, that is, instead of dynamically linking the corresponding shared object .so's. Because the semantics of private symbol calls from one Solaris library to another can change from one release to another, it is not a good practice to "hardwire" library code into your binary objects.
• Unbound symbols. These are library symbols (that is, functions or data) that the dynamic linker could not resolve when appcert was run. This might be an environment problem (for example, LD_LIBRARY_PATH) or a build problem (for example, not specifying -llib and/or -z defs with compiling). They are flagged to point these problems out and in case a more serious problem is indicated.

An entire product can be readily examined by appcert (that is, if the product is a collection of many programs and supporting shared objects) by referring appcert to the directories where the product is installed.

To perform its task, appcert constructs a profile of interface dependencies for each object file within the product (whether an executable object or shared object), to determine all the Solaris system interfaces that are depended upon. (Notice that appcert uses the Solaris runtime linker to make this determination.) These dependency profiles are then compared to a definition of the Solaris ABI to identify any interfaces that are Private (unsafe and unstable for application-level use).

appcert generates a simple roll-up report that indicates which of the product's components, if any, had liabilities and what those liabilities were. The report aids developers who are examining their product's release-to-release stability.

Notice that appcert produces complete interface dependency information, both the Public (safe and stable) Solaris interfaces and the Private (non-ABI) interfaces. This information can also be examined for each product component, if you want.

IMPORTANT: appcert must run in the same environment in which the application being checked runs. See NOTES.

The following options are supported:

-B

If appcert is run in "batch" mode, the output report will contain one line per binary, beginning with PASS if no problems were detected for the binary, FAIL if any problems were found, or INC if the binary could not be completely checked. Do not interpret these labels too literally. For example, PASS just means that none of the appcert warnings were triggered. These strings are flush left and so can be selected via grep ^FAIL ..., and so forth.

-f infile

Specifies the file infile that contains a list of files (one per line) to check. This list is appended to the list determined from the command line operands (see OPERANDS below).

-h

Prints out the usage information.

-L

appcert examines your product for the presence of shared objects. If it finds some, it appends the directories they reside in to LD_LIBRARY_PATH. Use this flag to prevent appcert from doing this.

-n

When searching directories for binaries to check, this option does not follow symbolic links. See find(1).

-S

Appends Solaris library directories (that is, /usr/openwin/lib:/usr/dt/lib) to LD_LIBRARY_PATH.

-w working_dir

Identifies the directory in which to run the library components and create temporary files (default is /tmp).

The following operands are supported:

{ obj | dir} ...

A complete list of objects and/or directories that contain the objects constituting the product to be checked. appcert recursively searches directories looking for object files; non-object files are ignored.

The following exit values are returned:

0

appcert ran successfully and found no potential binary stability problems.

1

appcert failed to run successfully.

2

Some of the objects checked have potential binary stability problems.

3

No binary objects were located that could be checked.

If the object file to be examined depends on libraries, those dependencies must be recorded in it (by using the compiler's -l switch).

If the object file to be examined depends on other shared libraries, those libraries must be accessible via LD_LIBRARY_PATH or RPATH when appcert is run.

To check 64-bit applications, the machine must be running the 64-bit Solaris kernel. See isalist(1). Also, the checks for static linking are currently not done on 64-bit applications.

appcert cannot examine:

• Object files that are completely or partially statically linked.

  Completely statically linked objects are reported as unstable.

• Executable files that do not have execute permission set.

  These are skipped. Shared objects without execute permission are not skipped.

• Object files that are setuid root.

  Due to limitations in ldd(1), these are skipped. Copy and/or change the permissions to check them.

• Non-ELF file executables such as shell scripts.
• Non-C language interfaces to Solaris; for example, C++ and Java.

  The code itself need not be in C as long as the calls to Solaris libaries are in C.

appcert records its findings in the following files in the working directory (/tmp/appcert.????? by default):

Index

A mapping between checked binaries and the subdirectory in the working directory in which the output specific to that binary can be found.

Report

A copy of the rollup report that was displayed on stdout when appcert was run.

Skipped

A list of binaries that appcert was asked to check but had to skip, along with a brief reason why each was skipped.

In addition, there is per-object information in the subdirectories under appcert.?????/objects/, in the following files:

check.demoted_symbols

A list of symbols suspected to be demoted Solaris symbols.

check.dynamic.private

A list of private Solaris symbols to which the object makes direct bindings.

check.dynamic.public

A list of public Solaris symbols to which the object makes direct bindings.

check.dynamic.unbound

A list of symbols not bound by the dynamic linker when ldd -r was run. For convenience, ldd output lines containing "file not found" are also included.

summary.dynamic

A pretty-printed summary of dynamic bindings for the objects examined, including tables of Public and Private symbols used from each Solaris library.

Other files are temporary files used internally by appcert.

Private Symbol Use

Demoted Symbols

Unbound Symbols

No Bindings Found

Obsolete Library

Use of sys_errlist/sys_nerr

Use of Strong vs. Weak Symbols

appcert needs to run in the same environment in which the application being checked runs. Otherwise it might not be able to resolve references correctly to interfaces in the Solaris libraries. Take the following steps:

1. Make sure that LD_LIBRARY_PATH and any other aspects of the environment are set to whatever settings are used when the application is run. Also make sure that it contains the directories containing any non-Solaris shared objects that are part of the product, so that they can be found when referenced.
2. Make sure that all the binaries to be checked:
   • Are dynamically linked ELF objects
   • Have execute permission set on executables (this is not necessary for shared objects)
   • Are not SUID root (otherwise you will have to be root to check them; make non-SUID copies and check those if necessary).

You might find it useful to write a shell script that sets up the environment correctly and then runs appcert.

Some potential problems that can be encountered are:

• appcert reports unbound symbols that appear to be part of Solaris libraries.

  This is probably caused when the application uses dlopen(3DL) to access a shared object that does not have its Solaris dependencies recorded. appcert cannot resolve symbol use in such cases, since the dynamic linker is never invoked on the shared object, and there is no other dependency information that could be used to resolve the Solaris symbol bindings. This can also occur with non-Solaris symbols.

  To avoid this problem, make sure that when a shared object is built, its dependencies on Solaris libraries are explicitly recorded by using the -llib option on the compile line (see cc(1) and ld(1)).

• appcert reports that the application uses a Solaris private symbol that is not referenced in the application's source code.

  This problem is most likely due to static linking of a Solaris library that references that symbol. Since appcert uses the dynamic linker to resolve symbols, statically linked libraries appear to appcert to be part of the application code (which, in a sense, they are). This can also sometimes happen as a result of macro substitution in a Solaris header file.

  To avoid this problem, whenever possible do not statically link Solaris library archives into your application.

• appcert does not recognize a library as part of Solaris.

  Some obsolete Solaris libraries are so old that they were obsoleted before their symbols could be versioned. Consequently, appcert cannot recognize them as being part of Solaris.

The use of the terms "public" and "private" as equivalent to "stable" and "unstable" is unfortunately somewhat confusing. In particular, experimental or evolving interfaces are public in the sense that they are documented and their use is encouraged. But they are unstable, because an application built with them might not run on subsequent releases. Thus, they are classified as private for appcert's purposes until they are no longer evolving. Conversely, obsolete interfaces will eventually disappear, and so are unstable, even though they have been public and stable in the past and are still treated as public by appcert. Fortunately, these two situations are rare.

See attributes(5) for descriptions of the following attributes:

cc(1), find(1), isalist(1), ld(1), ldd(1), ld.so.1(1), pvs(1), dlopen(3DL), strerror(3C), intro(4), attributes(5)

Linker and Libraries Guide