abidb(1) — Linux manual page
ABIDB(1) Libabigail ABIDB(1)
NAME
abidb - check binary against abixml corpus and/or submit new data
abidb manages a git repository of abixml files describing shared
libraries, and checks binaries against them. elfutils and
libabigail programs are used to query and process the binaries.
abidb works well with debuginfod to fetch needed DWARF content
automatically.
INVOCATION
abidb [OPTIONS] [--submit PATH1 PATH2 ...] [--check PATH1 PATH2 ...]
COMMON OPTIONS
• --abicompat PATH
Specify the path to the abicompat program to use. By
default, in the absence of this option, the abicompat
program found in directories listed in the $PATH environment
is used.
• --abidw PATH
Specify the path to the abidw program to use. By default,
in the absence of this option, the abidw program found in
directories listed in the $PATH environment is used.
• --distrobranch BRANCH
Specify the git branch for the abixml files in the git repo.
The default is a string like DISTRO/VERSION/ARCHITECTURE,
computed from the running environment.
• --git REPO
Specify the preexisting git working tree for abidb to submit
to or check against. The default is the current working
directory. It may be used concurrently by multiple "check"
operations, but only one "submit" operation.
• --help | -h
Display a short help about the command and exit.
• --loglevel LOGLEVEL
Specify the diagnostic level for messages to stderr. One of
debug, info, warning, error, or critical; case-insensitive.
The default is info.
• --timeout SECONDS
Specify a maximum limit to the execution time (in seconds)
allowed for the abidw and abicompat programs that are
executed. By default, no limit is set for the execution
time of these programs.
SUBMIT OPTIONS
• --archive | -Z .EXT[=CMD]
Designate PATH names with a .EXT suffix to be treated as
archives. If CMD is present, pipe the PATH through the
given shell command, otherwise pass as if through cat. The
resulting stream is then opened by libarchive, to enumerate
the contents of a wide variety of possible archive file
format. Process each file in the archive individually into
abixml.
For example, -Z .zip will process each file in a zip file,
and -Z .deb='dpkg-deb --fsys-tarfile' will process each
payload file in a Debian archive.
• --filter REGEX
Limit files selected for abixml extraction to those that
match the given regular expression. The default is
/lib.*\.so, as a heuristic to identify shared libraries.
• --submit PATH1 PATH2 ...
Using abidw, extract abixml for each of the listed files,
generally shared libraries, subject to the filename filter
and the archive decoding options. Save the output of each
abidw run into the selected distrobranch of the selected git
repo. If --submit and --check are both given, do submit
operations first.
• --sysroot PREFIX Specify the a prefix path that is to be
removed from submitted file names.
CHECK OPTIONS
• --check PATH1 PATH2 ...
Using abidiff, compare each of the listed file, generally
executables, against abixml documents for selected versions
for all shared libraries needed by the executable. These
are listed by enumerating the dynamic segment tags DT_NEEDED
of the executable.
• --ld-library-path DIR1:DIR2:DIR3...
Select the search paths for abixml documents used to locate
any particular SONAME . The first given directory wins.
However, all versions of the same SONAME in that directory
are selected for comparison. The default is unspecified,
which means to search for all matching SONAME entries in the
distrobranch, regardless of specific directory.
EXIT CODE
In case of successful submission and/or checking of all paths,
the exit code is 0.
In case of error, the exit code of abidb is nonzero, and a brief
listing of the binaries unable to be submitted and/or checked is
printed.
GIT REPOSITORY SCHEMA
abidb stores abixml documents in a git repo with the following
naming schema within the distrobranch:
1. The directory path leading to the shared library file
2. The SONAME of the shared library file, as a subdirectory name
3. A file named BUILDID.xml, where BUILDID is the hexadecimal ELF
build-id note of the shared library.
For example:
─────────────────────────────────────────────────────────────────────────────────────────────────
shared library file name abixml path in git
─────────────────────────────────────────────────────────────────────────────────────────────────
/usr/lib64/libc.so.6.2.32 /usr/lib64/libc.so.6/788cdd41a15985bf8e0a48d213a46e07d58822df.xml
/usr/lib64/libc.so.6.2.33 /usr/lib64/libc.so.6/e2ca832f1c2112aea9d7b9bc639e97e873a6b516.xml
/lib/ld-linux.so.2 /lib/ld-linux.so.2/b65f3c15b129f33f44f504da1719926aec03c07d.xml
─────────────────────────────────────────────────────────────────────────────────────────────────
│ │ │
│ The intent of includi│ng the buildid in the name is so that as a │
│ distro is updated wit│h multiple versions of a given shared │
│ library, they can be │represented nearby but non-conflicting. The │
│ SONAME is used in the│second-last name component, inspired the │
│ behavior of ld.so and│ldconfig, which rely on symbolic links to │
│ map references from t│he SONAME to an actual file. │
│ │ │
│SEE ALSO %%%SH%%% │ │
│ • ELF: │ │
│ http://en.wikipe │dia.org/wiki/Executable_and_Linkable_Format │
│ │ │
│ • DWARF: https://w │ww.dwarfstd.org │
│ │ │
│ • Debuginfod: http│s://sourceware.org/elfutils/Debuginfod.html │
│ │ │
│ • Git: https://git │-scm.com/ │
│ │ │
│ • Libarchive: http│s://www.libarchive.org/ │
│ │ │
│AUTHOR %%%SH%%% │ │
│ Frank Ch. Eigler │ │
│ │ │
│COPYRIGHT %%%SH%%% │ │
│ 2014-2022, Red Hat, I│nc. │
│ │ │
│COLOPHON %%%SH%%% │ │
│ This page is part of │the libabigail (ABI Generic Analysis and │
│ Instrumentation Libra│ry) project. Information about the project │
│ can be found at ⟨http│s://sourceware.org/libabigail/⟩. If you │
│ have a bug report for│this manual page, see │
│ ⟨http://sourceware.or│g/bugzilla/enter_bug.cgi?product=libabigail⟩. │
│ This page was obtaine│d from the project's upstream Git repository │
│ ⟨git://sourceware.org│/git/libabigail.git⟩ on 2024-06-14. (At │
│ that time, the date o│f the most recent commit that was found in │
│ the repository was 20│24-05-31.) If you discover any rendering │
│ problems in this HTML│version of the page, or you believe there │
│ is a better or more u│p-to-date source for the page, or you have │
│ corrections or improv│ements to the information in this COLOPHON │
│ (which is not part of│the original manual page), send a mail to │
│ man-pages@man7.org │ │
│ │ │
│ │ Jun 14, 2024 ABIDB(1) │
│ │ │
│ │ │
│ │ │
│ │ │
│ │ │
│ │ │
│ │ │
│ │ │
│ │ │
│ │ │
│ │ │
│ │ │
│ │ │
│ │ │
│ │ │
│ │ │
│ │ │
│ │ │