appcert man page on SunOS

Man page or keyword search:  
man Server   20652 pages
apropos Keyword Search (all sections)
Output format
SunOS logo
[printable version]

appcert(1)			 User Commands			    appcert(1)

NAME
       appcert	-  examine  application-level  products	 for  unstable	use of
       Solaris	interfaces

SYNOPSIS
       appcert [-h] [-n] [ -f  infile] [ -w  working_dir] [-B] [-L] [-S]  {obj
       | dir} ...

DESCRIPTION
       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 sym‐
	    bols, that is, functions or data, that are not intended for devel‐
	    oper  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" sym‐
	    bols), 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 indi‐
	    cated.

       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	depen‐
       dencies	for each object file within the product (whether an executable
       object or shared object), to determine all the  Solaris	system	inter‐
       faces  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  liabili‐
       ties 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 appli‐
       cation being checked runs. See NOTES.

OPTIONS
       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 OP‐
		       ERANDS 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 direc‐
		       tories 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).

OPERANDS
       The following operands are supported:

       { obj | dir}  ..A complete list of objects and/or directories that con‐
		       tain   the  objects  constituting  the  product	to  be
		       checked. appcert recursively searches directories look‐
		       ing for object files; non-object files are ignored.

EXIT STATUS
       The following exit values are returned:

       0	appcert ran successfully and found no potential binary stabil‐
		ity 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.

LIMITATIONS
       If the object file to be examined depends on libraries, those dependen‐
       cies 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 per‐
			mission 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.

OUTPUT FILES
       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 std‐
		       out 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.

OUTPUT MESSAGES
   Private Symbol Use
       Private symbols are functions or data variables in  a  Solaris  library
       that  are not intended for developer or external use. These symbols are
       interfaces that the Solaris libraries use to call and communicate  with
       one  another.  They are marked in pvs(1) output with the symbol version
       name "SUNWprivate".

       Private symbols can change their semantic behavior  or  even  disappear
       altogether  ("demoted"  or  "deprecated"	 symbols), so your application
       should not depend upon any of them.

   Demoted Symbols
       Demoted symbols are functions or data variables in  a  Solaris  library
       that were once private to that library and have been removed (or possi‐
       bly scoped local to the library) in a later Solaris  release.  If  your
       application  directly  calls one of these demoted symbols, it will fail
       to run (relocation error) on  the  release  in  which  the  symbol  was
       removed and releases thereafter.

       In  some	 rare  cases, a demoted symbol will return in a later release,
       but nevertheless there are still some releases on which the application
       will not run.

       Sun  Microsystems  Inc.	performed  most	 of the library scoping in the
       transition from Solaris 2.5.1 to 2.6. This action was done to  increase
       binary stability. By making these completely internal interfaces invis‐
       ible (that is, they cannot be dynamically linked against), a  developer
       cannot  accidentally  or	 intentionally call these interfaces. For more
       information, see the Linker and	Libraries  Guide,  in  particular  the
       chapter	 on   versioning.   This  document  may	 be  found  online  at
       http://docs.sun.com.

   Unbound Symbols
       Unbound symbols are library symbols (that is, functions or data) refer‐
       enced by the application that the dynamic linker could not resolve when
       appcert was run. Note: appcert does not actually run your  application,
       so  some	 aspect	 of the environment that affects dynamic linking might
       not be set properly.

       Unbound symbols do not necessarily indicate a potential binary  stabil‐
       ity  problem.  They  only  mean	that when appcert was run, the runtime
       dynamic linker could not resolve these symbols.

       Unbound symbols might be due to	LD_LIBRARY_PATH	 not  being  correctly
       set.  Make  sure it is set, so that all of your binary objects can find
       all of  the  libraries  they  depend  on	 (either  your	product's  own
       libraries,  Solaris  libraries, or those of a third party). Then re-run
       appcert.

       You might find it useful to write a shell script that sets up the envi‐
       ronment	correctly  and	then  runs appcert on the binaries you want to
       check.

       Another common cause for unbound symbols is when a shared object	 under
       test  has not recorded its dynamic dependencies, that is, at build time
       the -l switch was not supplied to the compiler and ld(1). So the shared
       object requires that the executables that link against it have the cor‐
       rect dependencies recorded.

       Notice that such a shared object can either be linked in	 the  standard
       way  (that  is, specified at an executable's build time) or dynamically
       opened (for example, an	executable  calls  dlopen(3C)  on  the	shared
       object  sometimes  when	running). Either case can give rise to unbound
       symbols when appcert is run. The former can usually be resolved by set‐
       ting  LD_LIBRARY_PATH  appropriately before running appcert. The latter
       (dlopen) is usually difficult to resolve. Under some circumstances, you
       might  be  able	to  set LD_PRELOAD appropriately to preload the needed
       libraries, but this procedure does not always work.

       How do you know if the environment has been set up  correctly  so  that
       there will be no unbound symbols? It must be set up so that running ldd
       -r on the binary yields no "file	 not  found"  or  "symbol  not	found"
       errors. See ld.so.1(1) and ldd(1) for more information on dynamic link‐
       ing.

       In any event, appcert flags unbound symbols as a warning in  case  they
       might  indicate a more serious problem. Unbound symbols can be an indi‐
       cator of dependencies  on  demoted  symbols  (symbols  that  have  been
       removed	from a library or scoped local to it). Dependencies on demoted
       symbols will lead to serious binary stability problems.

       However, setting up the environment properly should remove most unbound
       symbols. In general, it is good practice to record library dependencies
       at build time whenever possible because it helps make the binary object
       better  defined	and  self-contained.  Also recommended is using the -z
       defs flag when building shared objects, to force the resolution of  all
       symbols during compilation. See ld(1) for more information.

   No Bindings Found
       appcert	runs  /bin/ldd	-r on each binary object to be tested. It sets
       the environment variable	 LD_DEBUG="files,bindings".  (See  ldd(1)  and
       ld.so.1(1)  for	more information). If that command fails for some rea‐
       son, appcert will have no dynamic symbol binding information  and  will
       find "no bindings".

       appcert can fail if any of the following is true:

	 ·  The binary object does not have read permission.

	 ·  The	 binary object is SUID or SGID and the user does not have suf‐
	    ficient privileges.

	 ·  The binary object is an executable without the execute  permission
	    bit set.

	 ·  The binary object is completely statically linked.

	 ·  The binary object has no library dependency information recorded.

       Other  cases  exist  as	well (for example, out of memory). In general,
       this flag means that appcert could not completely  examine  the	object
       due  to	permissions  or	 environment. Try to modify the permissions or
       environment so that the dynamic bindings can be recorded.

   Obsolete Library
       An obsolete library is one whose use is deprecated and that  might,  in
       some  future release, be removed from Solaris altogether. appcert flags
       these because applications depending on them might not  run  in	future
       releases	 of  Solaris.  All  interfaces,	 including Private ones, in an
       obsolete library are frozen and will not change.

   Use of sys_errlist/sys_nerr
       Direct use of the symbols sys_errlist or sys_nerr presents  a  risk  in
       which  reference	 might	be made past the end of the sys_errlist array.
       These symbols are deprecated in 32-bit  versions	 of  Solaris  and  are
       absent altogether in 64-bit versions. Use strerror(3C) instead.

   Use of Strong vs. Weak Symbols
       The "strong" symbols (for example, _socket) associated with "weak" sym‐
       bols (for example, socket ) are reserved	 as  private  (their  behavior
       could change in the future). Your application should only directly ref‐
       erence the weak symbol (usually the strong symbols begin with "_").

       Note: Under  certain  build  environments,  the	strong/private	symbol
       dependency  gets	 recorded  into your binary instead of the weak/public
       one, even though the source code doesn't appear to reference  the  pri‐
       vate symbol. Nevertheless, steps should be taken to trace down why this
       is occurring and fix the dependency.

NOTES
       appcert needs to run in the same environment in which  the  application
       being  checked  runs.  Otherwise it might not be able to resolve refer‐
       ences correctly to interfaces in the Solaris libraries. Take  the  fol‐
       lowing steps:

       1.  Make	 sure  that LD_LIBRARY_PATH and any other aspects of the envi‐
	   ronment 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 neces‐
		sary 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 envi‐
       ronment 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(3C) 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 obso‐
	    leted before  their	 symbols  could	 be  versioned.	 Consequently,
	    appcert cannot recognize them as being part of Solaris.

BUGS
       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.

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

       ┌─────────────────────────────┬─────────────────────────────┐
       │      ATTRIBUTE TYPE	     │	    ATTRIBUTE VALUE	   │
       ├─────────────────────────────┼─────────────────────────────┤
       │Availability		     │SUNWapct			   │
       ├─────────────────────────────┼─────────────────────────────┤
       │Interface stability	     │Stable			   │
       └─────────────────────────────┴─────────────────────────────┘

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

       Linker and Libraries Guide

SunOS 5.10			  1 Mar 2004			    appcert(1)
[top]

List of man pages available for SunOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net