Provided by: abicheck_1.2-5_all bug

NAME

       abicheck  -  check  application  binaries  for  calls  to  private  or evolving symbols in
       libraries and for static linking of some system libraries.

SYNOPSIS

       abicheck [-h] [-k] [-a] [-I] [-v] [-f listfile] [-o outfile] [-p pattern] [-e pattern] [-j
       njobs]  [-l  library]  [-L  ldpath]  [(-s|-S)  dbfile]  [(-d|-D)  dbfile]  [-O dbfile] [-A
       listfile] files

DESCRIPTION

       abicheck is run on application binaries and issues warnings whenever any of the  following
       three conditions are detected:

       ·  Private  symbol  usage.   Private  symbols are functions or data variables in a library
       package that are internal to that package. They are used by the libraries in  the  package
       for  internal  communication  and  are not part of the API/ABI that application developers
       should use.

       · Evolving symbol usage.  Evolving symbols are functions or data variables  in  a  library
       package that are intended for developer consumption, but have been marked as "evolving" or
       "unstable" in the sense that they may become incompatible or disappear on a later  release
       of the library package.

       ·  Static  linking.   Static  linking  of  system  libraries (for example, libc.a) into an
       application is generally not a good idea because the system library code it  "locks"  into
       the application binary may become incompatible with later releases of the system. abicheck
       attempts to detect static linking of a few system libraries.

       The default behavior is, for each binary object checked, to examine direct calls from that
       binary object only. The -l option allows the libraries the binary object brings in to have
       their calls checked as well.

OPTIONS

       The following options are supported:

       -k     Keep on checking binaries even if there are serious errors (dynamic linker  reports
              unresolved symbols, ldd(1) failures, no symbols detected).

       -h     Print out long form of help.

       -v     Verbose.  Print out additional information.

       -f listfile
              The  listfile is a file containing a list of binary objects to check, one per line.
              This list is appended to any files provided as arguments on the command  line.   If
              listfile is "-", then stdin is used.

       -o outfile
              Write output to outfile instead of stdout.

       -p pattern
              Modify  the  version  name pattern match labelling private version sets. Default is
              /private/ using a case-insensitive match.

              If a component of the regex pattern contains two colons  in  a  row:  patt1::patt2,
              then symbol-level matching will be activated by checking whether version::symbol or
              library::symbol matches pattern (where the  symbol  name,  version  (if  any),  and
              library basename are substituted for symbol, version, and library).  For example,

                  -p 'FOO_VERS.*::_foopriv'
              or
                  -p 'libfoo.so.*::_foopriv'

       -e pattern
              Same as -p but  for "evolving" interfaces.

       -L ldpath
              Set  the  LD_LIBRARY_PATH  environment  variable  to ldpath before invoking dynamic
              linker.  Use -L "" to unset LD_LIBRARY_PATH.

              If one of the components of ldpath is the string "find", then all shared  libraries
              in  files  are  found and their paths inserted into the "find" location.  Note that
              the order will random.

       -l library
              Add the basename or full pathname of the shared library  library  to  the  list  of
              objects  to  be  checked  for making private calls. This option may occur more than
              once on the command line and is additive.  By default, only  direct  calls  from  a
              binary  to  the  system  libraries  are  checked.  The -l switch allows checking of
              indirect calls e.g.: app -> supportlib -> systemlib.

       -a     Loop through all of the binaries before checking and collect the list of all shared
              objects.   Take  the  basename of each shared object found and act as though it was
              specified with the -l option option and then run the abicheck  checks.   This  way,
              calls  from  all  "application  internal"  objects are checked rather than just the
              direct  calls.   (Useful  when  shared  objects  do  not  have  their  dependencies
              recorded.)

       -I     Ignore  shared  libraries in checking, only check executables.  Compatible with -a,
              libraries will be searched for first but then not checked.

       -d dbfile, -D dbfile
              Specify fallback flat-file symbol database for the  dynamic  (public  vs.  private)
              test.   These  classifications  will  be used if the library is not versioned (i.e.
              classification does not exist in the library itself).  Use -D to indicate that only
              information  from  dbfile  should  be used.  Lines in dbfile can be of one of these
              forms:

                   library|symbol
                   library|class|symbol
                   library|FILE=path

              library must be the full path to the library  to  be  specified  (it  cannot  be  a
              basename).

              The first form marks symbol as private.

              The  second  form  marks  symbol  with class where class may be public, private, or
              evolving.

              The third form indicates the file path should be opened on demand when  library  is
              first  encountered.  File path contains lines of the first two forms except for the
              library field.  The third form is a speedup to avoid processing many classification
              lines for libraries never encountered in the run.

       -O dbfile
              Specify  an  override  file  to  modify  the  symbol classification for the dynamic
              (public vs. private) test.  The format for the override file is like:

                   library|symbol|class

              The library can be the full path or basename.  If library is "__SKIP__" the  symbol
              will  be  ignored  for  any  library  it  is  found in.  The class can be "public",
              "private", "evolving", or "deleted".  The "deleted" class is  special-cased,  means
              the  symbol was deleted from the library on some release.  The symbol "__ALL__" for
              the "deleted" class means the entire library was deleted or is  otherwise  unstable
              to use.

              Examples:

                   libfoo.so.1|__bar|private
                   /lib/libxyz.so.1|baz|public
                   __SKIP__|__fputwc_xpg5

              These  settings  override  any  classification  inside  the  library  (from library
              versioning, obtainable from pvs(1), etc).

       -A listfile
              Set the ABI libraries of  interest  to  the  libraries  listed  in  listfile  (full
              pathnames,  one  per  line).   Only calls into these libraries will be checked; all
              other library calls will be ignored.

       -s dbfile, -S dbfile
              Specify more extensive symbol databases for the static linking test.  dbfile may be
              a  comma  separated  list  of  files.  If a file is a static archive (lib*.a) it is
              processed to extract the symbols.  Otherwise it is a database  file  consisting  of
              lines of the form symbol|library:module for example:

                      shmat|/usr/lib/libc.a:shmsys.o
                      shmctl|/usr/lib/libc.a:shmsys.o
                      shmdt|/usr/lib/libc.a:shmsys.o
                      shmget|/usr/lib/libc.a:shmsys.o
                      ...

              When  all  symbols  in a module.o are defined in the application, static linking of
              that module (and corresponding library archive) is assumed.   Use  -S  to  indicate
              that only the static link test should be performed.

              Use -S  int to do only the static link check and using the internal database.

              Use -s  none or -S  none to skip the static linking check entirely.

       -j njobs
              Run  njobs  in parallel as separate processes.  Implies -k.  Primarily intended for
              multiple CPU machines where njobs should be close  to  the  number  of  processors.
              Output is collected in tmp files and printed all at once near the end of the run as
              each job finishes.

              If njobs is "-", "detect", or "n", then njobs will be set to a number depending  on
              the number of processors on the current machine (if that can be determined).

OPERANDS

       The following operands are supported:

       files  A list of application binary objects to check.

OUTPUT

       There  is  one  line per problem (there may be multiple problems per binary checked) which
       look like the following:

              If no problems were found:
                  filename: OK

              If private symbol usage:
                  filename: PRIVATE (library:private_version) private_sym

              If evolving symbol usage:
                  filename: EVOLVING (library:evolving_vers) evolving_sym

              If file statically linked in a system archive library:
                  filename: STATIC_LINK (archive)

              If checking of the file was skipped:
                  filename: SKIP (reason)

       Under use of the deleted class in the -O override  file  option,  these  problems  may  be
       found:

              If a symbol has been deleted from the library on some release:
                  filename: DELETED_SYM: symbol/library

              (library will be "unbound" if the symbol was unbound)

              If  an  entire library has been deleted on some release or is otherwise unstable to
              use:
                 filename: UNSTABLE_LIB: library-soname = library-path

              (library-path may be "file not found" if the library could not be found)

       The following problems will cause a fatal error unless the -k option is used:

              If the dynamic linker could not resolve N symbols when ldd -r was run:
                  filename: UNBOUND_SYMBOLS: N

              If the dynamic linker found no dynamic bindings:
                  filename: NO_BINDINGS

              If ldd -r with LD_DEBUG=files,bindings failed:
                  filename: LDD_ERROR

       In these latter three cases run ldd -r on the binary file for  more  information  on  what
       went  wrong  (note  that  abicheck  runs ldd -r with LD_DEBUG=files,bindings set). On some
       systems the dynamic linker will not process SUID programs with LD_DEBUG set (this  usually
       results in NO_BINDINGS in the abicheck output).

       Note  that  if  you are running abicheck on a shared library (for example, libfoo.so) that
       has not been built with -l lib flags to record its library dependencies, then the "unbound
       symbols" problem is very likely. There is not much that can be done besides rebuilding the
       library or checking an application binary that uses the library and using the -l option of
       abicheck.

EXIT STATUS

       The following exit values are returned:

       0      No errors and no problems found.

       1      A fatal error occurred.

       2      No fatal errors occurred, but some binaries had problems detected.

NOTES

       Only ELF objects are checked.

       In the -s -S -d and -O dbfiles the '#' character starts a comment line in the usual way.

       Unless  one is using the "::" custom matches supplied via the -p or -e flags, abicheck can
       only check against system libraries that have had symbol versioning applied to them  (i.e.
       the  private  and/or evolving information recorded for each symbol in the library itself).
       For more info about symbol versioning,  see  the  "Solaris  Linker  and  Libraries  Guide"
       answerbook  at  the URL http://docs.sun.com/ab2/coll.45.13 and the Commands/Version-Script
       section of the GNU linker "ld" info page.

       The default symbol version name matching patterns are  case  insensitive  matches  to  the
       strings "private" and "evolving" for the private and evolving cases, respectively.

       Odd  filenames  containing  the  single-quote  character  or newline will be skipped; such
       characters interfere with calling commands via the shell.

       To recurse directories use find(1) and either collect the output to a file  for  use  with
       the -f option, or in a pipe in via:

               find ... | abicheck -f - ...

BUGS

       The  program  is  dependent  on the form of the runtime linker's debug output.  Since this
       output is intended to be human readable rather than machine readable, abicheck will  break
       whenever  the  output  format changes.  On Solaris it is possible that the Link Auditing C
       interface could be used to avoid this problem.

       On Linux when ldd(1) is run on a  SUID  binary,  it  (ldd  and  the  dynamic-linker)  will
       sometimes  actually run the binary. On Linux SUID/SGID binaries are currently skipped even
       if the user is root; test unprivileged copies instead.

SEE ALSO

       ld(1), ldd(1),

                                          26 August 2003                              abicheck(1)