abidb(1) — Linux manual page

NAME | INVOCATION | COMMON OPTIONS | SUBMIT OPTIONS | CHECK OPTIONS | EXIT CODE | GIT REPOSITORY SCHEMA

ABIDB(1)                       Libabigail                       ABIDB(1)

NAME         top

       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         top

          abidb [OPTIONS] [--submit PATH1 PATH2 ...] [--check PATH1 PATH2 ...]

COMMON OPTIONS         top

--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         top

--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         top

--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         top

       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         top

       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                          │
│      [email protected]   │                                                                   │
│                           │                                                                   │
│                           │ Jun 14, 2024                      ABIDB(1)                        │
│                           │                                                                   │
│                           │                                                                   │
│                           │                                                                   │
│                           │                                                                   │
│                           │                                                                   │
│                           │                                                                   │
│                           │                                                                   │
│                           │                                                                   │
│                           │                                                                   │
│                           │                                                                   │
│                           │                                                                   │
│                           │                                                                   │
│                           │                                                                   │
│                           │                                                                   │
│                           │                                                                   │
│                           │                                                                   │
│                           │                                                                   │
│                           │                                                                   │
│                           │                                                                   │