1ABIDIFF(1) Libabigail ABIDIFF(1)
2
6 abidiff - compare ABIs of ELF files
7 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 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 For a comprehensive ABI change report that includes changes about func‐
17 tion and variable sub-types, the two input shared libraries must be
18 accompanied with their debug information in DWARF format. Otherwise,
19 only ELF symbols that were added or removed are reported.
20
22 abidiff [options] <first-shared-library> <second-shared-library>
23
25 abidiff loads two default suppression specifications files, merges
26 their content and use it to filter out ABI change reports that might be
27 considered as false positives to users.
28 · Default system-wide suppression specification file
30 It’s located by the optional environment variable LIBABI‐
32 GAIL_DEFAULT_SYSTEM_SUPPRESSION_FILE. If that environment variable
33 is not set, then abidiff tries to load the suppression file $lib‐
34 dir/libabigail/libabigail-default.abignore. If that file is not
35 present, then no default system-wide suppression specification file
36 is loaded.
37 · Default user suppression specification file.
39 It’s located by the optional environment LIBABIGAIL_DEFAULT_USER_SUP‐
41 PRESSION_FILE. If that environment variable is not set, then abidiff
42 tries to load the suppression file $HOME/.abignore. If that file is
43 not present, then no default user suppression specification is
44 loaded.
45
47 · --help | -h
48 Display a short help about the command and exit.
50 · --version | -v
52 Display the version of the program and exit.
54 · --debug-info-dir1 | --d1 <di-path1>
56 For cases where the debug information for first-shared-library is
58 split out into a separate file, tells abidiff where to find that
59 separate debug information file.
60 Note that di-path must point to the root directory under which the
62 debug information is arranged in a tree-like manner. Under Red
63 Hat based systems, that directory is usually <root>/usr/lib/debug.
64 This option can be provided several times with different root
66 directories. In that case, abidiff will potentially look into all
67 those root directories to find the split debug info for
68 first-shared-library.
69 Note also that this option is not mandatory for split debug infor‐
71 mation installed by your system’s package manager because then
72 abidiff knows where to find it.
73 · --debug-info-dir2 | --d2 <di-path2>
75 Like --debug-info-dir1, this options tells abidiff where to find
77 the split debug information for the second-shared-library file.
78 This option can be provided several times with different root
80 directories. In that case, abidiff will potentially look into all
81 those root directories to find the split debug info for sec‐
82 ond-shared-library.
83 · --headers-dir1 | --hd1 <headers-directory-path-1>
85 Specifies where to find the public headers of the first shared
87 library that the tool has to consider. The tool will thus filter
88 out ABI changes on types that are not defined in public headers.
89 · --headers-dir2 | --hd2 <headers-directory-path-1>
91 Specifies where to find the public headers of the second shared
93 library that the tool has to consider. The tool will thus filter
94 out ABI changes on types that are not defined in public headers.
95 · --no-linux-kernel-mode
97 Without this option, if abidiff detects that the binaries it is
99 looking at are Linux Kernel binaries (either vmlinux or modules)
100 then it only considers functions and variables which ELF symbols
101 are listed in the __ksymtab and __ksymtab_gpl sections.
102 With this option, abidiff considers the binary as a non-special
104 ELF binary. It thus considers functions and variables which are
105 defined and exported in the ELF sense.
106 · --kmi-whitelist | -kaw <path-to-whitelist>
108 When analyzing a Linux kernel binary, this option points to the
110 white list of names of ELF symbols of functions and variables
111 which ABI must be considered. That white list is called a “Kernel
112 Module Interface white list”. This is because for the Kernel, we
113 don’t talk about ABI; we rather talk about the interface between
114 the Kernel and its module. Hence the term KMI rather than ABI.
115 Any other function or variable which ELF symbol are not present in
117 that white list will not be considered by this tool.
118 If this option is not provided – thus if no white list is provided
120 – then the entire KMI, that is, the set of all publicly defined
121 and exported functions and global variables by the Linux Kernel
122 binaries, is considered.
123 · --drop-private-types
125 This option is to be used with the --headers-dir1 and --head‐
127 ers-dir2 options. With this option, types that are NOT defined in
128 the headers are entirely dropped from the internal representation
129 build by Libabigail to represent the ABI. They thus don’t have to
130 be filtered out from the final ABI change report because they are
131 not even present in Libabigail’s representation.
132 Without this option however, those private types are kept in the
134 internal representation and later filtered out from the report.
135 This options thus potentially makes Libabigail consume less mem‐
137 ory. It’s meant to be mainly used to optimize the memory consump‐
138 tion of the tool on binaries with a lot of publicly defined and
139 exported types.
140 · --stat
142 Rather than displaying the detailed ABI differences between
144 first-shared-library and second-shared-library, just display some
145 summary statistics about these differences.
146 · --symtabs
148 Only display the symbol tables of the first-shared-library and
150 second-shared-library.
151 · --deleted-fns
153 In the resulting report about the differences between
155 first-shared-library and second-shared-library, only display the
156 globally defined functions that got deleted from
157 first-shared-library.
158 · --changed-fns
160 In the resulting report about the differences between
162 first-shared-library and second-shared-library, only display the
163 changes in sub-types of the global functions defined in
164 first-shared-library.
165 · --added-fns
167 In the resulting report about the differences between
169 first-shared-library and second-shared-library, only display the
170 globally defined functions that were added to sec‐
171 ond-shared-library.
172 · --deleted-vars
174 In the resulting report about the differences between
176 first-shared-library and second-shared-library, only display the
177 globally defined variables that were deleted from
178 first-shared-library.
179 · --changed-vars
181 In the resulting report about the differences between
183 first-shared-library and second-shared-library, only display the
184 changes in the sub-types of the global variables defined in
185 first-shared-library
186 · --added-vars
188 In the resulting report about the differences between
190 first-shared-library and second-shared-library, only display the
191 global variables that were added (defined) to sec‐
192 ond-shared-library.
193 · --no-added-syms
195 In the resulting report about the differences between
197 first-shared-library and second-shared-library, do not display
198 added functions or variables. Do not display added functions or
199 variables ELF symbols either. All other kinds of changes are dis‐
200 played unless they are explicitely forbidden by other options on
201 the command line.
202 · --no-linkage-name
204 In the resulting report, do not display the linkage names of the
206 added, removed, or changed functions or variables.
207 · --no-show-locs
209 Do not show information about where in the second shared library
210 the respective type was changed.
211 · --show-bytes
213 Show sizes and offsets in bytes, not bits. By default, sizes and
215 offsets are shown in bits.
216 · --show-bits
218 Show sizes and offsets in bits, not bytes. This option is acti‐
220 vated by default.
221 · --show-hex
223 Show sizes and offsets in hexadecimal base.
225 · --show-dec
227 Show sizes and offsets in decimal base. This option is activated
229 by default.
230 · --no-show-relative-offset-changes
232 Without this option, when the offset of a data member changes, the
234 change report not only mentions the older and newer offset, but it
235 also mentions by how many bits the data member changes. With this
236 option, the latter is not shown.
237 · --no-unreferenced-symbols
239 In the resulting report, do not display change information about
241 function and variable symbols that are not referenced by any debug
242 information. Note that for these symbols not referenced by any
243 debug information, the change information displayed is either
244 added or removed symbols.
245 · --no-default-suppression
247 Do not load the default suppression specification files.
249 · --suppressions | --suppr <path-to-suppressions>
251 Use a suppression specification file located at path-to-suppres‐
253 sions. Note that this option can appear multiple times on the
254 command line. In that case, all of the provided suppression spec‐
255 ification files are taken into account.
256 Please note that, by default, if this option is not provided, then
258 the default suppression specification files are loaded .
259 · --drop <regex>
261 When reading the first-shared-library and second-shared-library
263 ELF input files, drop the globally defined functions and variables
264 which name match the regular expression regex. As a result, no
265 change involving these functions or variables will be emitted in
266 the diff report.
267 · --drop-fn <regex>
269 When reading the first-shared-library and second-shared-library
271 ELF input files, drop the globally defined functions which name
272 match the regular expression regex. As a result, no change
273 involving these functions will be emitted in the diff report.
274 · --drop-var <regex>
276 When reading the first-shared-library and second-shared-library
278 ELF input files, drop the globally defined variables matching a
279 the regular expression regex.
280 · --keep <regex>
282 When reading the first-shared-library and second-shared-library
284 ELF input files, keep the globally defined functions and variables
285 which names match the regular expression regex. All other func‐
286 tions and variables are dropped on the floor and will thus not
287 appear in the resulting diff report.
288 · --keep-fn <regex>
290 When reading the first-shared-library and second-shared-library
292 ELF input files, keep the globally defined functions which name
293 match the regular expression regex. All other functions are
294 dropped on the floor and will thus not appear in the resulting
295 diff report.
296 · --keep-var <regex>
298 When reading the first-shared-library and second-shared-library
300 ELF input files, keep the globally defined which names match the
301 regular expression regex. All other variables are dropped on the
302 floor and will thus not appear in the resulting diff report.
303 · --harmless
305 In the diff report, display only the harmless changes. By
307 default, the harmless changes are filtered out of the diff report
308 keep the clutter to a minimum and have a greater chance to spot
309 real ABI issues.
310 · --no-harmful
312 In the diff report, do not display the harmful changes. By
314 default, only the harmful changes are displayed in diff report.
315 · --redundant
317 In the diff report, do display redundant changes. A redundant
319 change is a change that has been displayed elsewhere in the
320 report.
321 · --no-redundant
323 In the diff report, do NOT display redundant changes. A redundant
325 change is a change that has been displayed elsewhere in the
326 report. This option is switched on by default.
327 · --no-architecture
329 Do not take architecture in account when comparing ABIs.
331 · --no-corpus-path
333 Do not emit the path attribute for the ABI corpus.
335 · --fail-no-debug-info
337 If no debug info was found, then this option makes the program to
339 fail. Otherwise, without this option, the program will attempt to
340 compare properties of the binaries that are not related to debug
341 info, like pure ELF properties.
342 · --leaf-changes-only|-l only show leaf changes, so don’t show
344 impact analysis report.
345 The typical output of abidiff when comparing two binaries looks
347 like this
348 $ abidiff libtest-v0.so libtest-v1.so
350 Functions changes summary: 0 Removed, 1 Changed, 0 Added function
351 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
352 1 function with some indirect sub-type change:
354 [C]'function void fn(C&)' at test-v1.cc:13:1 has some indirect sub-type changes:
356 parameter 1 of type 'C&' has sub-type changes:
357 in referenced type 'struct C' at test-v1.cc:7:1:
358 type size hasn't changed
359 1 data member change:
360 type of 'leaf* C::m0' changed:
361 in pointed to type 'struct leaf' at test-v1.cc:1:1:
362 type size changed from 32 to 64 bits
363 1 data member insertion:
364 'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1
365 $
367 So in that example the report emits information about how the data
369 member insertion change of “struct leaf” is reachable from func‐
370 tion “void fn(C&)”. In other words, the report not only shows the
371 data member change on “struct leaf”, but it also shows the impact
372 of that change on the function “void fn(C&)”.
373 In abidiff parlance, the change on “struct leaf” is called a leaf
375 change. So the --leaf-changes-only --impacted-interfaces options
376 show, well, only the leaf change. And it goes like this:
377 $ abidiff -l libtest-v0.so libtest-v1.so
379 'struct leaf' changed:
380 type size changed from 32 to 64 bits
381 1 data member insertion:
382 'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1
383 one impacted interface:
385 function void fn(C&)
386 $
387 Note how the report ends by showing the list of interfaces
389 impacted by the leaf change.
390 Now if you don’t want to see that list of impacted interfaces,
392 then you can just avoid using the --impacted-interface option.
393 You can learn about that option below, in any case.
394 · --impacted-interfaces
396 When showing leaf changes, this option instructs abidiff to show
398 the list of impacted interfaces. This option is thus to be used
399 in addition the --leaf-changes-only option, otherwise, it’s
400 ignored.
401 · --dump-diff-tree
403 After the diff report, emit a textual representation of the diff
404 nodes tree used by the comparison engine to represent the
405 changed functions and variables. That representation is emitted
406 to the error output for debugging purposes. Note that this diff
407 tree is relevant only to functions and variables that have some
408 sub-type changes. Added or removed functions and variables do
409 not have any diff nodes tree associated to them.
410 · --stats
412 Emit statistics about various internal things.
414 · --verbose
416 Emit verbose logs about the progress of miscellaneous internal
418 things.
419
421 The exit code of the abidiff command is either 0 if the ABI of the
422 binaries being compared are equal, or non-zero if they differ or if the
423 tool encountered an error.
424 In the later case, the exit code is a 8-bits-wide bit field in which
426 each bit has a specific meaning.
427 The first bit, of value 1, named ABIDIFF_ERROR means there was an
429 error.
430 The second bit, of value 2, named ABIDIFF_USAGE_ERROR means there was
432 an error in the way the user invoked the tool. It might be set, for
433 instance, if the user invoked the tool with an unknown command line
434 switch, with a wrong number or argument, etc. If this bit is set, then
435 the ABIDIFF_ERROR bit must be set as well.
436 The third bit, of value 4, named ABIDIFF_ABI_CHANGE means the ABI of
438 the binaries being compared are different.
439 The fourth bit, of value 8, named ABIDIFF_ABI_INCOMPATIBLE_CHANGE means
441 the ABI of the binaries compared are different in an incompatible way.
442 If this bit is set, then the ABIDIFF_ABI_CHANGE bit must be set as
443 well. If the ABIDIFF_ABI_CHANGE is set and the ABIDIFF_INCOMPATI‐
444 BLE_CHANGE is NOT set, then it means that the ABIs being compared might
445 or might not be compatible. In that case, a human being needs to
446 review the ABI changes to decide if they are compatible or not.
447 Note that, at the moment, there are only a few kinds of ABI changes
449 that would result in setting the flag ABIDIFF_ABI_INCOMPATIBLE_CHANGE.
450 Those ABI changes are either:
451 · the removal of the symbol of a function or variable that has been
453 defined and exported.
454 · the modification of the index of a member of a virtual function
456 table (for C++ programs and libraries).
457 With time, when more ABI change patterns are found to always constitute
459 incompatible ABI changes, we will adapt the code to recognize those
460 cases and set the ABIDIFF_ABI_INCOMPATIBLE_CHANGE accordingly. So, if
461 you find such patterns, please let us know.
462 The remaining bits are not used for the moment.
464
466 1. Detecting a change in a sub-type of a function:
467 $ cat -n test-v0.cc
469 1 // Compile this with:
470 2 // g++ -g -Wall -shared -o libtest-v0.so test-v0.cc
471 3
472 4 struct S0
473 5 {
474 6 int m0;
475 7 };
476 8
477 9 void
478 10 foo(S0* /*parameter_name*/)
479 11 {
480 12 // do something with parameter_name.
481 13 }
482 $
483 $ cat -n test-v1.cc
484 1 // Compile this with:
485 2 // g++ -g -Wall -shared -o libtest-v1.so test-v1.cc
486 3
487 4 struct type_base
488 5 {
489 6 int inserted;
490 7 };
491 8
492 9 struct S0 : public type_base
493 10 {
494 11 int m0;
495 12 };
496 13
497 14 void
498 15 foo(S0* /*parameter_name*/)
499 16 {
500 17 // do something with parameter_name.
501 18 }
502 $
503 $ g++ -g -Wall -shared -o libtest-v0.so test-v0.cc
504 $ g++ -g -Wall -shared -o libtest-v1.so test-v1.cc
505 $
506 $ ../build/tools/abidiff libtest-v0.so libtest-v1.so
507 Functions changes summary: 0 Removed, 1 Changed, 0 Added function
508 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
509 1 function with some indirect sub-type change:
511 [C]'function void foo(S0*)' has some indirect sub-type changes:
513 parameter 0 of type 'S0*' has sub-type changes:
514 in pointed to type 'struct S0':
515 size changed from 32 to 64 bits
516 1 base class insertion:
517 struct type_base
518 1 data member change:
519 'int S0::m0' offset changed from 0 to 32
520 $
521 2. Detecting another change in a sub-type of a function:
523 $ cat -n test-v0.cc
525 1 // Compile this with:
526 2 // g++ -g -Wall -shared -o libtest-v0.so test-v0.cc
527 3
528 4 struct S0
529 5 {
530 6 int m0;
531 7 };
532 8
533 9 void
534 10 foo(S0& /*parameter_name*/)
535 11 {
536 12 // do something with parameter_name.
537 13 }
538 $
539 $ cat -n test-v1.cc
540 1 // Compile this with:
541 2 // g++ -g -Wall -shared -o libtest-v1.so test-v1.cc
542 3
543 4 struct S0
544 5 {
545 6 char inserted_member;
546 7 int m0;
547 8 };
548 9
549 10 void
550 11 foo(S0& /*parameter_name*/)
551 12 {
552 13 // do something with parameter_name.
553 14 }
554 $
555 $ g++ -g -Wall -shared -o libtest-v0.so test-v0.cc
556 $ g++ -g -Wall -shared -o libtest-v1.so test-v1.cc
557 $
558 $ ../build/tools/abidiff libtest-v0.so libtest-v1.so
559 Functions changes summary: 0 Removed, 1 Changed, 0 Added function
560 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
561 1 function with some indirect sub-type change:
563 [C]'function void foo(S0&)' has some indirect sub-type changes:
565 parameter 0 of type 'S0&' has sub-type changes:
566 in referenced type 'struct S0':
567 size changed from 32 to 64 bits
568 1 data member insertion:
569 'char S0::inserted_member', at offset 0 (in bits)
570 1 data member change:
571 'int S0::m0' offset changed from 0 to 32
572 $
575 3. Detecting that functions got removed or added to a library:
577 $ cat -n test-v0.cc
579 1 // Compile this with:
580 2 // g++ -g -Wall -shared -o libtest-v0.so test-v0.cc
581 3
582 4 struct S0
583 5 {
584 6 int m0;
585 7 };
586 8
587 9 void
588 10 foo(S0& /*parameter_name*/)
589 11 {
590 12 // do something with parameter_name.
591 13 }
592 $
593 $ cat -n test-v1.cc
594 1 // Compile this with:
595 2 // g++ -g -Wall -shared -o libtest-v1.so test-v1.cc
596 3
597 4 struct S0
598 5 {
599 6 char inserted_member;
600 7 int m0;
601 8 };
602 9
603 10 void
604 11 bar(S0& /*parameter_name*/)
605 12 {
606 13 // do something with parameter_name.
607 14 }
608 $
609 $ g++ -g -Wall -shared -o libtest-v0.so test-v0.cc
610 $ g++ -g -Wall -shared -o libtest-v1.so test-v1.cc
611 $
612 $ ../build/tools/abidiff libtest-v0.so libtest-v1.so
613 Functions changes summary: 1 Removed, 0 Changed, 1 Added functions
614 Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
615 1 Removed function:
617 'function void foo(S0&)' {_Z3fooR2S0}
618 1 Added function:
620 'function void bar(S0&)' {_Z3barR2S0}
621 $
623
625 Dodji Seketeli
626
628 2014-2019, Red Hat, Inc.
629 Jul 25, 2019 ABIDIFF(1)