1ABIDIFF(1)                        Libabigail                        ABIDIFF(1)
2
3
4

NAME

6       abidiff - compare ABIs of ELF files
7
8       abidiff  compares the Application Binary Interfaces (ABI) of two shared
9       libraries in ELF format.  It emits a meaningful report  describing  the
10       differences between the two ABIs.
11
12       This  tool  can  also compare the textual representations of the ABI of
13       two ELF binaries (as emitted by abidw) or an ELF binary against a  tex‐
14       tual representation of another ELF binary.
15
16       For  a  comprehensive  ABI  change  report between two input shared li‐
17       braries that includes changes about function  and  variable  sub-types,
18       abidiff uses by default, debug information in DWARF format, if present,
19       otherwise it compares interfaces using debug information in CTF format,
20       if  present,  finally, if neither is found, it uses only ELF symbols to
21       report which of them were added or removed.
22
23       This tool uses the libabigail library to analyze the binary as well  as
24       its  associated  debug information.  Here is its general mode of opera‐
25       tion.
26
27       When instructed to do so, a binary and its associated debug information
28       is  read  and analyzed.  To that effect, libabigail analyzes by default
29       the descriptions of the types reachable by  the  interfaces  (functions
30       and  variables)  that  are  visible  outside of their translation unit.
31       Once that analysis is done, an Application Binary Interface  Corpus  is
32       constructed  by only considering the subset of types reachable from in‐
33       terfaces associated to ELF symbols that are defined and exported by the
34       binary.   It’s that final ABI corpus which libabigail considers as rep‐
35       resenting the ABI of the analyzed binary.
36
37       Libabigail then has capabilities to generate textual representations of
38       ABI Corpora, compare them, analyze their changes and report about them.
39

INVOCATION

41          abidiff [options] <first-shared-library> <second-shared-library>
42

ENVIRONMENT

44       abidiff  loads  two  default  suppression  specifications files, merges
45       their content and use it to filter out ABI change reports that might be
46       considered as false positives to users.
47
48       • Default system-wide suppression specification file
49
50         It’s  located  by  the  optional  environment variable LIBABIGAIL_DE‐
51         FAULT_SYSTEM_SUPPRESSION_FILE.  If that environment variable  is  not
52         set,  then abidiff tries to load the suppression file $libdir/libabi‐
53         gail/libabigail-default.abignore.  If that file is not present,  then
54         no default system-wide suppression specification file is loaded.
55
56       • Default user suppression specification file.
57
58         It’s located by the optional environment LIBABIGAIL_DEFAULT_USER_SUP‐
59         PRESSION_FILE.  If that environment variable is not set, then abidiff
60         tries  to load the suppression file $HOME/.abignore.  If that file is
61         not present,  then  no  default  user  suppression  specification  is
62         loaded.
63

OPTIONS

65--help | -h
66
67            Display a short help about the command and exit.
68
69--debug-self-comparison
70
71            In this mode, error messages are emitted for types which fail type
72            canonicalization, in some circumstances, when comparing  a  binary
73            against itself.
74
75            When  comparing  a  binary  against itself, canonical types of the
76            second binary should be equal (as much as possible)  to  canonical
77            types  of  the first binary.  When some discrepancies are detected
78            in this mode, an abort signal is emitted and execution is  halted.
79            This option should be used while executing the tool in a debugger,
80            for troubleshooting purposes.
81
82            This is an optional debugging and sanity check option.  To  enable
83            it  the  libabigail  package  needs to be configured with the –en‐
84            able-debug-self-comparison configure option.
85
86--debug-tc
87
88            In this mode, the process of type canonicalization  is  put  under
89            heavy  scrutiny.   Basically,  during  type canonicalization, each
90            type comparison is performed twice:  once  in  a  structural  mode
91            (comparing  every  sub-type member-wise), and once using canonical
92            comparison.  The two comparisons should  yield  the  same  result.
93            Otherwise,  an  abort signal is emitted and the process can be de‐
94            bugged to understand why the two kinds of comparison yield differ‐
95            ent results.
96
97            This  is an optional debugging and sanity check option.  To enable
98            it the libabigail package needs to be  configured  with  the  –en‐
99            able-debug-type-canonicalization configure option.
100
101--version | -v
102
103            Display the version of the program and exit.
104
105--debug-info-dir1 | --d1 <di-path1>
106
107            For  cases where the debug information for first-shared-library is
108            split out into a separate file, tells abidiff where to  find  that
109            separate debug information file.
110
111            Note that di-path must point to the root directory under which the
112            debug information is arranged in a tree-like  manner.   Under  Red
113            Hat based systems, that directory is usually <root>/usr/lib/debug.
114
115            This  option can be provided several times with different root di‐
116            rectories.  In that case, abidiff will potentially look  into  all
117            those   root   directories  to  find  the  split  debug  info  for
118            first-shared-library.
119
120            Note also that this option is not mandatory for split debug infor‐
121            mation  installed  by  your  system’s package manager because then
122            abidiff knows where to find it.
123
124--debug-info-dir2 | --d2 <di-path2>
125
126            Like --debug-info-dir1, this options tells abidiff where  to  find
127            the split debug information for the second-shared-library file.
128
129            This  option can be provided several times with different root di‐
130            rectories.  In that case, abidiff will potentially look  into  all
131            those  root  directories  to  find  the  split debug info for sec‐
132            ond-shared-library.
133
134--headers-dir1 | --hd1 <headers-directory-path-1>
135
136            Specifies where to find the public headers of the first shared li‐
137            brary  (or  binary in general) that the tool has to consider.  The
138            tool will thus filter out ABI changes on types that  are  not  de‐
139            fined in public headers.
140
141            Note  that  several public header directories can be specified for
142            the first shared library.  In that case the --headers-dir1  option
143            should  be  present several times on the command line, like in the
144            following example:
145
146                $ abidiff --headers-dir1 /some/path       \
147                          --headers-dir1 /some/other/path \
148                          binary-version-1 binary-version-2
149
150--header-file1 | --hf1 <header-file-path-1>
151
152            Specifies where to find one public header of the first shared  li‐
153            brary  that  the  tool has to consider.  The tool will thus filter
154            out ABI changes on types that are not defined in public headers.
155
156--headers-dir2 | --hd2 <headers-directory-path-2>
157
158            Specifies where to find the public headers of  the  second  shared
159            library  that the tool has to consider.  The tool will thus filter
160            out ABI changes on types that are not defined in public headers.
161
162            Note that several public header directories can be  specified  for
163            the second shared library.  In that case the --headers-dir2 option
164            should be present several times like in the following example:
165
166                $ abidiff --headers-dir2 /some/path       \
167                          --headers-dir2 /some/other/path \
168                          binary-version-1 binary-version-2
169
170--header-file2 | --hf2 <header-file-path-2>
171
172            Specifies where to find one public header of the second shared li‐
173            brary  that  the  tool has to consider.  The tool will thus filter
174            out ABI changes on types that are not defined in public headers.
175
176--no-linux-kernel-mode
177
178            Without this option, if abidiff detects that the  binaries  it  is
179            looking  at  are Linux Kernel binaries (either vmlinux or modules)
180            then it only considers functions and variables which  ELF  symbols
181            are listed in the __ksymtab and __ksymtab_gpl sections.
182
183            With  this  option,  abidiff considers the binary as a non-special
184            ELF binary.  It thus considers functions and variables  which  are
185            defined and exported in the ELF sense.
186
187--kmi-whitelist | -kaw <path-to-whitelist>
188
189            When  analyzing  a  Linux kernel binary, this option points to the
190            white list of names of ELF  symbols  of  functions  and  variables
191            which ABI must be considered.  That white list is called a “Kernel
192            Module Interface white list”.  This is because for the Kernel,  we
193            don’t  talk  about ABI; we rather talk about the interface between
194            the Kernel and its module. Hence the term KMI rather than ABI.
195
196            Any other function or variable which ELF symbol are not present in
197            that white list will not be considered by this tool.
198
199            If this option is not provided – thus if no white list is provided
200            – then the entire KMI, that is, the set of  all  publicly  defined
201            and  exported  functions  and global variables by the Linux Kernel
202            binaries, is considered.
203
204--drop-private-types
205
206            This option is to be used with the  --headers-dir1,  header-file1,
207            header-file2  and --headers-dir2 options.  With this option, types
208            that are NOT defined in the headers are entirely dropped from  the
209            internal  representation build by Libabigail to represent the ABI.
210            They thus don’t have to be filtered out from the final ABI  change
211            report because they are not even present in Libabigail’s represen‐
212            tation.
213
214            Without this option however, those private types are kept  in  the
215            internal representation and later filtered out from the report.
216
217            This  options  thus potentially makes Libabigail consume less mem‐
218            ory.  It’s meant to be mainly used to optimize the memory consump‐
219            tion  of  the  tool on binaries with a lot of publicly defined and
220            exported types.
221
222--exported-interfaces-only
223
224            By default, when looking at the debug information  accompanying  a
225            binary, this tool analyzes the descriptions of the types reachable
226            by the interfaces (functions and variables) that are visible  out‐
227            side  of  their  translation unit.  Once that analysis is done, an
228            ABI corpus is constructed by only considering the subset of  types
229            reachable  from  interfaces associated to ELF symbols that are de‐
230            fined and exported by the binary.  It’s those  final  ABI  Corpora
231            that are compared by this tool.
232
233            The  problem  with that approach however is that analyzing all the
234            interfaces that are visible from outside  their  translation  unit
235            can  amount  to  a lot of data, especially when those binaries are
236            applications, as opposed to shared libraries.  One example of such
237            applications is the
238            `Linux Kernel`_
239            .  Analyzing massive ABI corpora like these can be extremely slow.
240
241            To  mitigate that performance issue, this option allows libabigail
242            to only analyze types that are reachable from  interfaces  associ‐
243            ated with defined and exported ELF symbols.
244
245            Note that this option is turned on by default when analyzing the
246
247            `Linux Kernel`_
248            .  Otherwise, it’s turned off by default.
249
250--allow-non-exported-interfaces
251
252            When  looking at the debug information accompanying a binary, this
253            tool analyzes the descriptions of the types reachable by  the  in‐
254            terfaces  (functions  and  variables)  that are visible outside of
255            their translation unit.  Once that analysis is done, an ABI corpus
256            is  constructed  by only considering the subset of types reachable
257            from interfaces associated to ELF symbols that are defined and ex‐
258            ported  by the binary.  It’s those final ABI Corpora that are com‐
259            pared by this tool.
260
261            The problem with that approach however is that analyzing  all  the
262            interfaces  that  are  visible from outside their translation unit
263            can amount to a lot of data, especially when  those  binaries  are
264            applications, as opposed to shared libraries.  One example of such
265            applications is the
266            `Linux Kernel`_
267            .  Analyzing massive ABI Corpora like these can be extremely slow.
268
269            In the presence of an “average sized” binary however one  can  af‐
270            ford  having  libabigail  analyze  all interfaces that are visible
271            outside of their translation unit, using this option.
272
273            Note that this option is turned on by default, unless  we  are  in
274            the presence of the
275            `Linux Kernel`_
276            .
277
278--stat
279
280            Rather  than  displaying  the  detailed  ABI  differences  between
281            first-shared-library and second-shared-library, just display  some
282            summary statistics about these differences.
283
284--symtabs
285
286            Only  display  the  symbol  tables of the first-shared-library and
287            second-shared-library.
288
289--deleted-fns
290
291            In  the   resulting   report   about   the   differences   between
292            first-shared-library  and  second-shared-library, only display the
293            globally defined functions that got deleted from  first-shared-li‐
294            brary.
295
296--changed-fns
297
298            In   the   resulting   report   about   the   differences  between
299            first-shared-library and second-shared-library, only  display  the
300            changes   in   sub-types   of  the  global  functions  defined  in
301            first-shared-library.
302
303--added-fns
304
305            In  the   resulting   report   about   the   differences   between
306            first-shared-library  and  second-shared-library, only display the
307            globally defined functions that were  added  to  second-shared-li‐
308            brary.
309
310--deleted-vars
311
312            In   the   resulting   report   about   the   differences  between
313            first-shared-library and second-shared-library, only  display  the
314            globally defined variables that were deleted from first-shared-li‐
315            brary.
316
317--changed-vars
318
319            In  the   resulting   report   about   the   differences   between
320            first-shared-library  and  second-shared-library, only display the
321            changes in the  sub-types  of  the  global  variables  defined  in
322            first-shared-library
323
324--added-vars
325
326            In   the   resulting   report   about   the   differences  between
327            first-shared-library and second-shared-library, only  display  the
328            global  variables  that  were added (defined) to second-shared-li‐
329            brary.
330
331--non-reachable-types|-t
332
333            Analyze and emit change reports for all the types of  the  binary,
334            including  those  that are not reachable from global functions and
335            variables.
336
337            This option might incur some serious  performance  degradation  as
338            the number of types analyzed can be huge.  However, if paired with
339            the --headers-dir{1,2} and/or header-file{1,2} options, the  addi‐
340            tional  non-reachable  types  analyzed are restricted to those de‐
341            fined in public headers files, thus hopefully making  the  perfor‐
342            mance hit acceptable.
343
344            Also,  using  this option alongside suppression specifications (by
345            also using the --suppressions option) might help keep  the  number
346            of  analyzed  types (and the potential performance degradation) in
347            control.
348
349            Note that without this option, only types that are reachable  from
350            global  functions  and variables are analyzed, so the tool detects
351            and reports changes on these reachable types only.
352
353--no-added-syms
354
355            In  the   resulting   report   about   the   differences   between
356            first-shared-library  and  second-shared-library,  do  not display
357            added functions or variables.  Do not display added  functions  or
358            variables ELF symbols either.  All other kinds of changes are dis‐
359            played unless they are explicitely forbidden by other  options  on
360            the command line.
361
362--no-linkage-name
363
364            In  the  resulting report, do not display the linkage names of the
365            added, removed, or changed functions or variables.
366
367--no-show-locs
368              Do not show information about where in the second shared library
369              the respective type was changed.
370
371--show-bytes
372
373            Show  sizes and offsets in bytes, not bits.  By default, sizes and
374            offsets are shown in bits.
375
376--show-bits
377
378            Show sizes and offsets in bits, not bytes.  This option  is  acti‐
379            vated by default.
380
381--show-hex
382
383            Show sizes and offsets in hexadecimal base.
384
385--show-dec
386
387            Show  sizes and offsets in decimal base.  This option is activated
388            by default.
389
390--ignore-soname
391
392            Ignore differences in the SONAME when doing a comparison
393
394--no-show-relative-offset-changes
395
396            Without this option, when the offset of a data member changes, the
397            change report not only mentions the older and newer offset, but it
398            also mentions by how many bits the data member changes.  With this
399            option, the latter is not shown.
400
401--no-unreferenced-symbols
402
403            In  the  resulting report, do not display change information about
404            function and variable symbols that are not referenced by any debug
405            information.   Note  that  for these symbols not referenced by any
406            debug information, the  change  information  displayed  is  either
407            added or removed symbols.
408
409--no-default-suppression
410
411            Do not load the default suppression specification files.
412
413--suppressions | --suppr <path-to-suppressions>
414
415            Use  a  suppression specification file located at path-to-suppres‐
416            sions.  Note that this option can appear  multiple  times  on  the
417            command line.  In that case, all of the provided suppression spec‐
418            ification files are taken into account.
419
420            Please note that, by default, if this option is not provided, then
421            the default suppression specification files are loaded .
422
423--drop <regex>
424
425            When  reading  the  first-shared-library and second-shared-library
426            ELF input files, drop the globally defined functions and variables
427            which  name  match  the regular expression regex.  As a result, no
428            change involving these functions or variables will be  emitted  in
429            the diff report.
430
431--drop-fn <regex>
432
433            When  reading  the  first-shared-library and second-shared-library
434            ELF input files, drop the globally defined  functions  which  name
435            match  the  regular  expression regex.  As a result, no change in‐
436            volving these functions will be emitted in the diff report.
437
438--drop-var <regex>
439
440            When reading the  first-shared-library  and  second-shared-library
441            ELF  input  files,  drop the globally defined variables matching a
442            the regular expression regex.
443
444--keep <regex>
445
446            When reading the  first-shared-library  and  second-shared-library
447            ELF input files, keep the globally defined functions and variables
448            which names match the regular expression regex.  All  other  func‐
449            tions and variables are dropped on the floor and will thus not ap‐
450            pear in the resulting diff report.
451
452--keep-fn <regex>
453
454            When reading the  first-shared-library  and  second-shared-library
455            ELF  input  files,  keep the globally defined functions which name
456            match the regular  expression  regex.   All  other  functions  are
457            dropped  on  the  floor  and will thus not appear in the resulting
458            diff report.
459
460--keep-var <regex>
461
462            When reading the  first-shared-library  and  second-shared-library
463            ELF  input  files, keep the globally defined which names match the
464            regular expression regex.  All other variables are dropped on  the
465            floor and will thus not appear in the resulting diff report.
466
467--harmless
468
469            In  the  diff  report,  display only the harmless changes.  By de‐
470            fault, the harmless changes are filtered out of  the  diff  report
471            keep  the  clutter  to a minimum and have a greater chance to spot
472            real ABI issues.
473
474--no-harmful
475
476            In the diff report, do not display the harmful  changes.   By  de‐
477            fault, only the harmful changes are displayed in diff report.
478
479--redundant
480
481            In  the  diff  report,  do display redundant changes.  A redundant
482            change is a change that has been displayed elsewhere  in  the  re‐
483            port.
484
485--no-redundant
486
487            In the diff report, do NOT display redundant changes.  A redundant
488            change is a change that has been displayed elsewhere  in  the  re‐
489            port.  This option is switched on by default.
490
491--no-architecture
492
493            Do not take architecture in account when comparing ABIs.
494
495--no-corpus-path
496
497            Do not emit the path attribute for the ABI corpus.
498
499--fail-no-debug-info
500
501            If  no debug info was found, then this option makes the program to
502            fail.  Otherwise, without this option, the program will attempt to
503            compare  properties  of the binaries that are not related to debug
504            info, like pure ELF properties.
505
506--leaf-changes-only|-l only show leaf changes, so don’t  show  im‐
507            pact analysis report.  This option implies --redundant.
508
509            The  typical  output  of abidiff when comparing two binaries looks
510            like this
511
512                $ abidiff libtest-v0.so libtest-v1.so
513                Functions changes summary: 0 Removed, 1 Changed, 0 Added function
514                Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
515
516                1 function with some indirect sub-type change:
517
518                  [C]'function void fn(C&)' at test-v1.cc:13:1 has some indirect sub-type changes:
519                    parameter 1 of type 'C&' has sub-type changes:
520                      in referenced type 'struct C' at test-v1.cc:7:1:
521                        type size hasn't changed
522                        1 data member change:
523                         type of 'leaf* C::m0' changed:
524                           in pointed to type 'struct leaf' at test-v1.cc:1:1:
525                             type size changed from 32 to 64 bits
526                             1 data member insertion:
527                               'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1
528
529                $
530
531            So in that example the report emits information about how the data
532            member  insertion  change of “struct leaf” is reachable from func‐
533            tion “void fn(C&)”.  In other words, the report not only shows the
534            data  member change on “struct leaf”, but it also shows the impact
535            of that change on the function “void fn(C&)”.
536
537            In abidiff parlance, the change on “struct leaf” is called a  leaf
538            change.   So the --leaf-changes-only --impacted-interfaces options
539            show, well, only the leaf change.  And it goes like this:
540
541                $ abidiff -l libtest-v0.so libtest-v1.so
542                'struct leaf' changed:
543                  type size changed from 32 to 64 bits
544                  1 data member insertion:
545                    'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1
546
547                  one impacted interface:
548                    function void fn(C&)
549                $
550
551            Note how the report ends by showing the  list  of  interfaces  im‐
552            pacted by the leaf change.
553
554            Now  if  you  don’t  want to see that list of impacted interfaces,
555            then you can just avoid  using  the  --impacted-interface  option.
556            You can learn about that option below, in any case.
557
558--impacted-interfaces
559
560            When  showing  leaf changes, this option instructs abidiff to show
561            the list of impacted interfaces.  This option is thus to  be  used
562            in  addition  the  --leaf-changes-only option, otherwise, it’s ig‐
563            nored.
564
565--dump-diff-tree
566              After the diff report, emit a textual representation of the diff
567              nodes  tree  used  by  the  comparison  engine  to represent the
568              changed functions and variables.  That representation is emitted
569              to the error output for debugging purposes.  Note that this diff
570              tree is relevant only to functions and variables that have  some
571              sub-type  changes.   Added or removed functions and variables do
572              not have any diff nodes tree associated to them.
573
574--no-assume-odr-for-cplusplus
575
576            When analysing a binary originating from C++ code using DWARF  de‐
577            bug  information,  libabigail  assumes  the One Definition Rule to
578            speed-up the analysis.  In that case, when several types have  the
579            same name in the binary, they are assumed to all be equal.
580
581            This  option  disables that assumption and instructs libabigail to
582            actually actually compare the  types  to  determine  if  they  are
583            equal.
584
585--no-leverage-dwarf-factorization
586
587            When  analysing  a  binary  which DWARF debug information was pro‐
588            cessed with the DWZ tool, the type information is supposed  to  be
589            already factorized.  That context is used by libabigail to perform
590            some speed optimizations.
591
592            This option disables those optimizations.
593
594--ctf
595
596            When comparing binaries, extract ABI information  from  CTF  debug
597            information, if present.
598
599--stats
600
601            Emit statistics about various internal things.
602
603--verbose
604
605            Emit  verbose  logs  about  the progress of miscellaneous internal
606            things.
607

RETURN VALUES

609       The exit code of the abidiff command is either 0 if the ABI of the  bi‐
610       naries  being  compared are equal, or non-zero if they differ or if the
611       tool encountered an error.
612
613       In the later case, the exit code is a 8-bits-wide bit  field  in  which
614       each bit has a specific meaning.
615
616       The  first  bit, of value 1, named ABIDIFF_ERROR means there was an er‐
617       ror.
618
619       The second bit, of value 2, named ABIDIFF_USAGE_ERROR means  there  was
620       an  error  in  the way the user invoked the tool.  It might be set, for
621       instance, if the user invoked the tool with  an  unknown  command  line
622       switch, with a wrong number or argument, etc.  If this bit is set, then
623       the ABIDIFF_ERROR bit must be set as well.
624
625       The third bit, of value 4, named ABIDIFF_ABI_CHANGE means  the  ABI  of
626       the binaries being compared are different.
627
628       The fourth bit, of value 8, named ABIDIFF_ABI_INCOMPATIBLE_CHANGE means
629       the ABI of the binaries compared are different in an incompatible  way.
630       If  this  bit  is  set,  then the ABIDIFF_ABI_CHANGE bit must be set as
631       well.  If the ABIDIFF_ABI_CHANGE  is  set  and  the  ABIDIFF_INCOMPATI‐
632       BLE_CHANGE is NOT set, then it means that the ABIs being compared might
633       or might not be compatible.  In that case, a human being needs  to  re‐
634       view the ABI changes to decide if they are compatible or not.
635
636       Note  that,  at  the  moment, there are only a few kinds of ABI changes
637       that would result in setting the flag  ABIDIFF_ABI_INCOMPATIBLE_CHANGE.
638       Those ABI changes are either:
639
640          • the  removal of the symbol of a function or variable that has been
641            defined and exported.
642
643          • the modification of the index of a member of  a  virtual  function
644            table (for C++ programs and libraries).
645
646       With time, when more ABI change patterns are found to always constitute
647       incompatible ABI changes, we will adapt the  code  to  recognize  those
648       cases  and set the ABIDIFF_ABI_INCOMPATIBLE_CHANGE accordingly.  So, if
649       you find such patterns, please let us know.
650
651       The remaining bits are not used for the moment.
652

USAGE EXAMPLES

654          1. Detecting a change in a sub-type of a function:
655
656                 $ cat -n test-v0.cc
657                          1      // Compile this with:
658                          2      //   g++ -g -Wall -shared -o libtest-v0.so test-v0.cc
659                          3
660                          4      struct S0
661                          5      {
662                          6        int m0;
663                          7      };
664                          8
665                          9      void
666                         10      foo(S0* /*parameter_name*/)
667                         11      {
668                         12        // do something with parameter_name.
669                         13      }
670                 $
671                 $ cat -n test-v1.cc
672                          1      // Compile this with:
673                          2      //   g++ -g -Wall -shared -o libtest-v1.so test-v1.cc
674                          3
675                          4      struct type_base
676                          5      {
677                          6        int inserted;
678                          7      };
679                          8
680                          9      struct S0 : public type_base
681                         10      {
682                         11        int m0;
683                         12      };
684                         13
685                         14      void
686                         15      foo(S0* /*parameter_name*/)
687                         16      {
688                         17        // do something with parameter_name.
689                         18      }
690                 $
691                 $ g++ -g -Wall -shared -o libtest-v0.so test-v0.cc
692                 $ g++ -g -Wall -shared -o libtest-v1.so test-v1.cc
693                 $
694                 $ ../build/tools/abidiff libtest-v0.so libtest-v1.so
695                 Functions changes summary: 0 Removed, 1 Changed, 0 Added function
696                 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
697
698                 1 function with some indirect sub-type change:
699
700                   [C]'function void foo(S0*)' has some indirect sub-type changes:
701                         parameter 0 of type 'S0*' has sub-type changes:
702                           in pointed to type 'struct S0':
703                             size changed from 32 to 64 bits
704                             1 base class insertion:
705                               struct type_base
706                             1 data member change:
707                              'int S0::m0' offset changed from 0 to 32
708                 $
709
710          2. Detecting another change in a sub-type of a function:
711
712                 $ cat -n test-v0.cc
713                          1      // Compile this with:
714                          2      //   g++ -g -Wall -shared -o libtest-v0.so test-v0.cc
715                          3
716                          4      struct S0
717                          5      {
718                          6        int m0;
719                          7      };
720                          8
721                          9      void
722                         10      foo(S0& /*parameter_name*/)
723                         11      {
724                         12        // do something with parameter_name.
725                         13      }
726                 $
727                 $ cat -n test-v1.cc
728                          1      // Compile this with:
729                          2      //   g++ -g -Wall -shared -o libtest-v1.so test-v1.cc
730                          3
731                          4      struct S0
732                          5      {
733                          6        char inserted_member;
734                          7        int m0;
735                          8      };
736                          9
737                         10      void
738                         11      foo(S0& /*parameter_name*/)
739                         12      {
740                         13        // do something with parameter_name.
741                         14      }
742                 $
743                 $ g++ -g -Wall -shared -o libtest-v0.so test-v0.cc
744                 $ g++ -g -Wall -shared -o libtest-v1.so test-v1.cc
745                 $
746                 $ ../build/tools/abidiff libtest-v0.so libtest-v1.so
747                 Functions changes summary: 0 Removed, 1 Changed, 0 Added function
748                 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
749
750                 1 function with some indirect sub-type change:
751
752                   [C]'function void foo(S0&)' has some indirect sub-type changes:
753                         parameter 0 of type 'S0&' has sub-type changes:
754                           in referenced type 'struct S0':
755                             size changed from 32 to 64 bits
756                             1 data member insertion:
757                               'char S0::inserted_member', at offset 0 (in bits)
758                             1 data member change:
759                              'int S0::m0' offset changed from 0 to 32
760
761
762                 $
763
764          3. Detecting that functions got removed or added to a library:
765
766                 $ cat -n test-v0.cc
767                          1      // Compile this with:
768                          2      //   g++ -g -Wall -shared -o libtest-v0.so test-v0.cc
769                          3
770                          4      struct S0
771                          5      {
772                          6        int m0;
773                          7      };
774                          8
775                          9      void
776                         10      foo(S0& /*parameter_name*/)
777                         11      {
778                         12        // do something with parameter_name.
779                         13      }
780                 $
781                 $ cat -n test-v1.cc
782                          1      // Compile this with:
783                          2      //   g++ -g -Wall -shared -o libtest-v1.so test-v1.cc
784                          3
785                          4      struct S0
786                          5      {
787                          6        char inserted_member;
788                          7        int m0;
789                          8      };
790                          9
791                         10      void
792                         11      bar(S0& /*parameter_name*/)
793                         12      {
794                         13        // do something with parameter_name.
795                         14      }
796                 $
797                 $ g++ -g -Wall -shared -o libtest-v0.so test-v0.cc
798                 $ g++ -g -Wall -shared -o libtest-v1.so test-v1.cc
799                 $
800                 $ ../build/tools/abidiff libtest-v0.so libtest-v1.so
801                 Functions changes summary: 1 Removed, 0 Changed, 1 Added functions
802                 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
803
804                 1 Removed function:
805                   'function void foo(S0&)'    {_Z3fooR2S0}
806
807                 1 Added function:
808                   'function void bar(S0&)'    {_Z3barR2S0}
809
810                 $
811

AUTHOR

813       Dodji Seketeli
814
816       2014-2022, Red Hat, Inc.
817
818
819
820
821                                 Dec 02, 2022                       ABIDIFF(1)
Impressum