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 ] [ -f listfile ] [ -l library ]  [  -L
     ldpath ] [ -p pattern ] [ -e pattern ] files

DESCRIPTION

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

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

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

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

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

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

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

     -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, ver-
     sion (if any), and library basename are substituted for sym-
     bol, version, and library).  For example,

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

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

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  prob-
     lems 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)


     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  sys-
     tems  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 appli-
     cation  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  prob-
          lems detected.

NOTES

     Only ELF objects are checked.

     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  new-
     line will be skipped; such characters interfere with calling
     commands via the shell.

     This program will not run with Perl version 4 or lower.

BUGS

     On Solaris 2.6 elfdump(1) (called by this script) will some-
     times fail with "Segmentation Fault - core dumped" when part
     of a pipeline.

     On Linux when ldd(1) is run on a SUID binary,  it  (ldd  and
     the  dynamic-linker) will sometimes actually RUN the binary.
     To be on the safe side do not run abicheck on SUID  or  SGID
     binaries; test unprivileged copies instead.

SEE ALSO

     ld(1), ldd(1),