Man Linux: Main Page and Category List


       icheck - C interface ABI/API checker


       icheck --canonify [[--baseline FILE] ...]  [OPTIONS] [GCC_OPTIONS] [--]

       icheck --compare [OPTIONS] old_file new_file


       A tool for statically checking C interfaces for API  and  ABI  changes.
       All  changes  to type declarations that can cause ABI changes should be
       detected, along with most API changes.

       icheck is intended for use with libraries, as a  method  of  preventing
       ABI drift.


       Reduce  a  set  of  source  files  to  a  canonical interface file with
       --canonify, then compare two such interface files  with  --compare.  If
       there  are  interface  changes  between  them, icheck will describe the
       changes and fail.

       --canonify [[--baseline FILE] ...]  [OPTIONS] [GCC_OPTIONS] [--] files

              Canonify the source code files  (typically  .h  headers)  to  be
              compared  later  with --compare. Usually used with the -o option
              to save the summary to a file.

       --compare [OPTIONS] old_file new_file

              Reads two canonical interface files  generated  with  --canonify
              and  compares the structure of the source code to the changes in
              the Application Public Interface  (the  developer  interface  or
              API)  and  the  Application  Binary Interface (ABI) used to link
              against other programs or libraries.


       -o, --output FILE

              Emit output to FILE, rather than stdout.

       --debug N

              Dump debugging information.

       --only THING

              Only process the given THING.

       --skip-from FILE

              Skip unnecessary things from FILE.

       --skip-from-re regexp

              Skip  unnecessary  things  from  files  matching   the   regular

       --only-from FILE

              Only take things from FILE.

       --only-from-re regexp

              Only take things from files matching the regular expression.


              GCC_OPTIONS are passed through to gcc -E

              Display the help synopsis for icheck.


       All  source files are preprocessed with gcc, so canonify needs the same
       include information as the source code - follow  the  syntax  from  the
       Makefile  to  include  -I options to cpp (or gcc) so that all necessary
       headers can be located. icheck  will  abort  if  any  required  headers
       cannot  be found. The source must be compileable; icheck cannot process
       files which cannot  be  directly  compiled.  If  a  header  is  missing
       #include statements, or otherwise requires being used in a special way,
       then it cannot be directly processed with icheck. Instead, write a stub
       C file that sets things up appropriately and then #includes the header.

       icheck   --canonify   -o   ~/icheck/oldversion   -I/usr/include/foo-2.0

       Prepare  a text summary of the foobar.h file and all files it includes.
       The  summary  is  written  out  to  ~/icheck/oldversion.   Repeat   for
       /usr/src/bar1/src/foobar.h   -  the  same  file  in  the  newer  source
       directory, outputting to a new file, e.g.  ~/icheck/newversion.

       icheck   --compare    -o    ~/icheck/results.txt    ~/icheck/oldversion

       Writes  the  report  of  the  comparison  of the two summary files. The
       report indicates all the changes in the ABI and/or API found during the

       icheck     --canonify    -o    debian/icheck.canonical    -Idebian/foo-
       dev/usr/include debian/foo-dev/usr/include/foobar.h

       icheck --compare debian/icheck.manifest debian/icheck.canonical

       These two statements, included in a debian/rules file, will  cause  the
       package build to fail if the API or ABI has changed in unexpected ways,
       where icheck.manifest is a copy of the expected interface, included  in
       the package.

       Note that the arguments to --compare are themselves valid C files which
       are preprocessed, so icheck.manifest can contain C preprocessor  logic.
       This  can  be  useful  when  a  package  exports  different  interfaces
       depending on the host architecture. In this case, you can’t replace  it
       with  a new copy of icheck.canonical when the interface changes and you
       need to update the manifest. Rather than updating the  entire  manifest
       by  hand,  put  the  hand-written  interface  descriptions  in one file
       (icheck.static-manifest) and then use:

       icheck   --canonify   --baseline    debian/icheck.static-manifest    -o

       Lastly, create icheck.manifest containing:
       #include "icheck.static-manifest"
       #include "icheck.dynamic-manifest"
       This  allows  you  to  update some parts of the manifest by hand, while
       still automatically generating the rest.


       icheck generates a lengthly description of every possible  API  or  ABI
       change,  based  on type information. It does not investigate the actual
       program code, and so it is possible that some type changes  it  detects
       are  not actual ABI or API changes. However, this normally only happens
       when the program code was explicitly  written  for  it.  If  in  doubt,
       assume it’s changed.

       At  the  end,  icheck  provides a summary of the changes. Note that the
       directions here  are  dependent  on  the  order  of  the  arguments  to
       --compare:  the older interface must come first, or the directions will
       be the other way around. The meanings  of  the  various  terms  are  as

              ABI    The  ABI  is  compatible  if  things compiled against one
                     version of the interface will work  when  run  using  the
                     other version.

              API    The  API  is  compatible  if  things compiled against one
                     version of the interface  can  be  compiled  against  the

                     An  interface  is  forwards-compatible if things compiled
                     against the old version will work with the new.  This  is
                     the important feature for soname changes.

                     An  interface  is backwards-compatible if things compiled
                     against the new version will work with the old.  This  is
                     the  important feature for shlibs version changes. If you
                     aren’t building Debian packages, you probably don’t  care
                     about changes which aren’t backwards-compatible.


       icheck was written by Andrew Suffield <>.

       This  manual  page  was written by Neil Williams <>
       and Andrew Suffield <>.