abidiff(1)

Från Wiki.linux.se - Svensk Linux Wiki
Version från den 10 januari 2026 kl. 06.27 av Admin (diskussion | bidrag)
Hoppa till navigering Hoppa till sök

ABIDIFF(1)

NAMN

abidiff – jämför ABI:er för ELF-filer.

abidiff jämför applikationsbinärgränssnitt (ABI, Application Binary Interface) för två delade bibliotek i ELF-format (Executable and Linkable Format). Verktyget skriver ut en meningsfull rapport som beskriver skillnaderna mellan de två ABI:erna.

Det här verktyget kan också jämföra de textuella representationerna av ABI:t för två ELF-binärer (såsom de skrivs ut av abidw), eller jämföra en ELF-binär mot en textuell representation av en annan ELF-binär.

För en omfattande ABI-ändringsrapport mellan två indata-delade bibliotek (som även inkluderar ändringar i funktions- och variabelundertypers strukturer) använder abidiff som standard felsökningsinformation i DWARF-format om den finns. Om DWARF saknas jämför den i stället med felsökningsinformation i CTF- eller BTF-format, om sådan finns. Om ingen felsökningsinformation i dessa format hittas, beaktas enbart ELF-symboler och verktyget rapporterar då om symboler har lagts till eller tagits bort.

Det här verktyget använder biblioteket libabigail för att analysera binären och dess associerade felsökningsinformation. Så här fungerar det i stora drag:

När du instruerar verktyget läses en binär och dess associerade felsökningsinformation in och analyseras. Libabigail analyserar som standard typbeskrivningar som kan nås från gränssnitt (funktioner och variabler) som är synliga utanför sin översättningsenhet. När analysen är klar konstrueras en ABI-korpus (ABI Corpus) genom att endast beakta den delmängd av typer som kan nås från gränssnitt kopplade till ELF-symboler som är definierade och exporterade av binären. Det är denna slutliga ABI-korpus som libabigail betraktar som binärens ABI.

Libabigail kan sedan generera textuella representationer av ABI-korpusar, jämföra dem, analysera ändringar och rapportera om dem.

ANROP

abidiff [alternativ] <första-delade-biblioteket> <andra-delade-biblioteket>

MILJÖ

abidiff läser in två förvalda undertryckningsspecifikationsfiler (suppression specifications), slår ihop deras innehåll och använder detta för att filtrera bort ABI-ändringar som kan betraktas som falska positiva resultat.

  • Förvald systemomfattande undertryckningsfil
 Platsen kan anges med miljövariabeln LIBABIGAIL_DEFAULT_SYSTEM_SUPPRESSION_FILE. Om den inte är satt försöker abidiff läsa filen $libdir/libabigail/libabigail-default.abignore. Om filen inte finns laddas ingen förvald systemomfattande undertryckningsfil.
  • Förvald användarundertryckningsfil
 Platsen kan anges med miljövariabeln LIBABIGAIL_DEFAULT_USER_SUPPRESSION_FILE. Om den inte är satt försöker abidiff läsa filen $HOME/.abignore. Om filen inte finns laddas ingen förvald användarundertryckningsfil.

ALTERNATIV

Flagga Argument 
abidiff --headers-dir1 /some/path \
       --headers-dir1 /some/other/path \
       binary-version-1 binary-version-2
--headers-dir2
--hd2 		<headers-katalog-2>

RETURVÄRDEN

Returkoden från abidiff är antingen 0 om ABI:t för binärerna som jämförs är lika, eller icke-noll om de skiljer sig eller om verktyget stötte på ett fel.

I det senare fallet är returkoden ett 8-bitars bitfält där varje bit har en specifik betydelse:

  • Bit 1 (värde 1), ABIDIFF_ERROR: ett fel inträffade.
  • Bit 2 (värde 2), ABIDIFF_USAGE_ERROR: fel i hur användaren anropade verktyget (okänd flagga, fel antal argument, osv). Om denna bit är satt måste även ABIDIFF_ERROR vara satt.
  • Bit 3 (värde 4), ABIDIFF_ABI_CHANGE: ABI:t skiljer sig mellan binärerna.
  • Bit 4 (värde 8), ABIDIFF_ABI_INCOMPATIBLE_CHANGE: ABI:t skiljer sig på ett inkompatibelt sätt. Om denna bit är satt måste även ABIDIFF_ABI_CHANGE vara satt. Om ABIDIFF_ABI_CHANGE är satt men ABIDIFF_ABI_INCOMPATIBLE_CHANGE inte är satt betyder det att ABI:erna kan vara kompatibla eller inte; en människa behöver då granska ändringarna.

För närvarande finns bara några få typer av ABI-ändringar som alltid leder till att ABIDIFF_ABI_INCOMPATIBLE_CHANGE sätts:

  • Borttagning av symbolen för en funktion eller variabel som varit definierad och exporterad.
  • Ändring av index för en medlem i en virtuell funktionstabell (för C++-program och -bibliotek).

Med tiden kan fler mönster identifieras som alltid utgör inkompatibla ändringar; då kommer koden att uppdateras för att känna igen dessa fall. Om du hittar sådana mönster, rapportera dem gärna.

Övriga bitar används inte för tillfället.

ANVÄNDNINGSEXEMPEL

1. Upptäcka en ABI-ändring i en undertyp till en funktion

$ cat -n test-v0.cc
         1      // Compile this with:
         2      //   g++ -g -Wall -shared -o libtest-v0.so test-v0.cc
         3
         4      struct S0
         5      {
         6        int m0;
         7      };
         8
         9      void
        10      foo(S0* /*parameter_name*/)
        11      {
        12        // do something with parameter_name.
        13      }
$
$ cat -n test-v1.cc
         1      // Compile this with:
         2      //   g++ -g -Wall -shared -o libtest-v1.so test-v1.cc
         3
         4      struct type_base
         5      {
         6        int inserted;
         7      };
         8
         9      struct S0 : public type_base
        10      {
        11        int m0;
        12      };
        13
        14      void
        15      foo(S0* /*parameter_name*/)
        16      {
        17        // do something with parameter_name.
        18      }
$
$ g++ -g -Wall -shared -o libtest-v0.so test-v0.cc
$ g++ -g -Wall -shared -o libtest-v1.so test-v1.cc
$
$ abidiff libtest-v0.so libtest-v1.so; echo "exit code: $?"
Functions changes summary: 0 Removed, 1 Changed, 0 Added function
Variables changes summary: 0 Removed, 0 Changed, 0 Added variable

1 function with some indirect sub-type change:

  [C]'function void foo(S0*)' has some indirect sub-type changes:
        parameter 0 of type 'S0*' has sub-type changes:
          in pointed to type 'struct S0':
            size changed from 32 to 64 bits
            1 base class insertion:
              struct type_base
            1 data member change:
             'int S0::m0' offset changed from 0 to 32
exit code: 4
$

Notera att returkoden är 4, vilket betyder att biten ABIDIFF_ABI_CHANGE (värde 4) är satt. Det innebär att verktyget kategoriserar ändringen som skadlig och att en mänsklig granskning krävs.

2. Upptäcka en inkompatibel ABI-ändring i typen för en funktion

$ cat -n test-v0.cc
     1  // Compile this with:
     2  //   g++ -g -Wall -shared -o libtest-v0.so test-v0.cc
     3
     4  struct S0
     5  {
     6    int m0;
     7  };
     8
     9  S0
    10  foo()
    11  {
    12    S0 s = {};
    13    return s;
    14  }
$
$ cat -n test-v1.cc
     1  // Compile this with:
     2  //   g++ -g -Wall -shared -o libtest-v1.so test-v1.cc
     3
     4  struct type_base
     5  {
     6    int inserted;
     7  };
     8
     9  struct S0 : public type_base
    10  {
    11    int m0;
    12  };
    13
    14  S0
    15  foo()
    16  {
    17    S0 s = {};
    18    return s;
    19  }
$
$ g++ -g -Wall -shared -o libtest-v0.so test-v0.cc
$ g++ -g -Wall -shared -o libtest-v1.so test-v1.cc
$
$ abidiff libtest-v0.so libtest-v1.so; echo "exit code: $?"
Functions changes summary: 0 Removed, 1 Changed, 0 Added function
Variables changes summary: 0 Removed, 0 Changed, 0 Added variable

1 function with incompatible sub-type changes:

  [C] 'function S0 foo(void)' at test-v0.cc:10:1 has some sub-type changes:
    return type changed:
      type size changed from 32 to 64 (in bits)
      1 base class insertion:
        struct type_base at test-v1.cc:4:1
      1 data member change:
        'int m0' offset changed from 0 to 32 (in bits) (by +32 bits)

exit code: 12
$

Notera att returkoden är 12, vilket betyder att både ABIDIFF_ABI_CHANGE (4) och ABIDIFF_ABI_INCOMPATIBLE_CHANGE (8) är satta. Det betyder att verktyget kategoriserar ändringen som inkompatibel – ett ABI-brott.

3. Upptäcka ytterligare en ändring i en undertyp till en funktion

$ cat -n test-v0.cc
         1      // Compile this with:
         2      //   g++ -g -Wall -shared -o libtest-v0.so test-v0.cc
         3
         4      struct S0
         5      {
         6        int m0;
         7      };
         8
         9      void
        10      foo(S0& /*parameter_name*/)
        11      {
        12        // do something with parameter_name.
        13      }
$
$ cat -n test-v1.cc
         1      // Compile this with:
         2      //   g++ -g -Wall -shared -o libtest-v1.so test-v1.cc
         3
         4      struct S0
         5      {
         6        char inserted_member;
         7        int m0;
         8      };
         9
        10      void
        11      foo(S0& /*parameter_name*/)
        12      {
        13        // do something with parameter_name.
        14      }
$
$ g++ -g -Wall -shared -o libtest-v0.so test-v0.cc
$ g++ -g -Wall -shared -o libtest-v1.so test-v1.cc
$
$ abidiff libtest-v0.so libtest-v1.so; echo "exit code: $?"
Functions changes summary: 0 Removed, 1 Changed, 0 Added function
Variables changes summary: 0 Removed, 0 Changed, 0 Added variable

1 function with some indirect sub-type change:

  [C]'function void foo(S0&)' has some indirect sub-type changes:
        parameter 0 of type 'S0&' has sub-type changes:
          in referenced type 'struct S0':
            size changed from 32 to 64 bits
            1 data member insertion:
              'char S0::inserted_member', at offset 0 (in bits)
            1 data member change:
             'int S0::m0' offset changed from 0 to 32

exit code: 4
$

4. Upptäcka att funktioner har tagits bort eller lagts till i ett bibliotek

$ cat -n test-v0.cc
         1      // Compile this with:
         2      //   g++ -g -Wall -shared -o libtest-v0.so test-v0.cc
         3
         4      struct S0
         5      {
         6        int m0;
         7      };
         8
         9      void
        10      foo(S0& /*parameter_name*/)
        11      {
        12        // do something with parameter_name.
        13      }
$
$ cat -n test-v1.cc
         1      // Compile this with:
         2      //   g++ -g -Wall -shared -o libtest-v1.so test-v1.cc
         3
         4      struct S0
         5      {
         6        char inserted_member;
         7        int m0;
         8      };
         9
        10      void
        11      bar(S0& /*parameter_name*/)
        12      {
        13        // do something with parameter_name.
        14      }
$
$ g++ -g -Wall -shared -o libtest-v0.so test-v0.cc
$ g++ -g -Wall -shared -o libtest-v1.so test-v1.cc
$
$ abidiff libtest-v0.so libtest-v1.so; echo "exit code: $?"
Functions changes summary: 1 Removed, 0 Changed, 1 Added functions
Variables changes summary: 0 Removed, 0 Changed, 0 Added variable

1 Removed function:
  'function void foo(S0&)'    {_Z3fooR2S0}

1 Added function:
  'function void bar(S0&)'    {_Z3barR2S0}

exit code: 12
$

5. Jämföra två uppsättningar binärer via kommandoraden

$ abidiff --add-binaries1=file2-v1              \
          --add-binaries2=file2-v2,file2-v1     \
          --added-binaries-dir1 dir1            \
          --added-binaries-dir2 dir2            \
          file1-v1 file1-v2

Observera att filerna file2-v1 och file2-v2 ska finnas i dir1 och dir2 eller i aktuell katalog.

6. Jämföra två bibliotek och deras beroenden

$ abidiff --follow-dependencies                      \
          --added-binaries-dir1 /some/where          \
          --added-binaries-dir2 /some/where/else     \
          foo bar

Detta jämför uppsättningen binärer bestående av foo och dess beroenden mot uppsättningen bestående av bar och dess beroenden.

FÖRFATTARE

Dodji Seketeli

UPPHOVSRÄTT

2014–2025, Red Hat, Inc.

KOLOFON

Den här sidan ingår i projektet libabigail (ABI Generic Analysis and Instrumentation Library). Information om projektet finns på: [1](https://sourceware.org/libabigail/)

För felrapport för manualsidan, se: [2](http://sourceware.org/bugzilla/enter_bug.cgi?product=libabigail)

Den här sidan hämtades från projektets uppströms Git-repo (git://sourceware.org/git/libabigail.git) den 2025-08-11. Vid den tidpunkten var datumet för den senaste commit som hittades i repot 2025-07-28.

Om du upptäcker renderingsproblem i HTML-versionen, eller tror att det finns en bättre/nyare källa för sidan, eller har korrigeringar/förbättringar till informationen i detta KOLOFON-avsnitt (som inte är del av originalmanualen), skicka e-post till [man-pages@man7.org](mailto:man-pages@man7.org)
Hämtad från "https://wiki.linux.se/index.php?title=abidiff(1)&oldid=8417"