ABIDW(1) Libabigail ABIDW(1)

abidw - سریال‌سازی ABI یک فایل ELF

دستور abidw یک کتابخانه اشتراکی در قالب ELF http://en.wikipedia.org/wiki/Executable_and_Linkable_Format را خوانده و یک بازنمود XML از ABI آن را در خروجی استاندارد منتشر می‌کند. قالب بازنمود ارائه‌شده، با نام ABIXML، شامل تمامی توابع و متغیرهای سراسری تعریف‌شده به همراه بازنمودی کامل از نوع‌های داده آن‌ها است. این خروجی همچنین شامل بازنمودی از نمادهای ELF تعریف‌شده به‌صورت سراسری در فایل است.

هنگامی که گزینه --linux-tree داده شود، این برنامه می‌تواند یک درخت هسته لینوکس https://kernel.org را نیز مدیریت کند؛ به این معنی که یک درخت دایرکتوری شامل باینری vmlinux و ماژول‌های هسته لینوکس https://kernel.org را بررسی می‌کند. این ابزار باینری‌های هسته لینوکس https://kernel.org را تحلیل کرده و بازنمود XML رابط بین هسته و ماژول‌های آن را در خروجی استاندارد منتشر می‌سازد. در این حالت، به آن ABI نمی‌گوییم، بلکه آن را KMI (رابط ماژول هسته یا Kernel Module Interface) می‌نامیم. KMI منتشرشده شامل تمامی توابع و متغیرهای تعریف‌شده به‌صورت سراسری به همراه بازنمود کاملی از نوع‌های آن‌ها است.

برای تولید بازنمود ABI یا KMI، دستور abidw به‌طور پیش‌فرض از اطلاعات دیباگ در قالب DWARF http://www.dwarfstd.org (در صورت وجود) استفاده می‌کند؛ در غیر این صورت، به دنبال اطلاعات دیباگ در قالب‌های CTF https://raw.githubusercontent.com/wiki/oracle/binutils-gdb/files/ctf-spec.pdf یا BTF https://docs.kernel.org/bpf/btf.html (در صورت وجود) می‌گردد. در نهایت، اگر هیچ اطلاعات دیباگی در این قالب‌ها یافت نشود، تنها نمادهای ELF http://en.wikipedia.org/wiki/Executable_and_Linkable_Format را در نظر گرفته و افزودن یا حذف آن‌ها را گزارش می‌دهد.

این ابزار از کتابخانه libabigail برای تحلیل باینری و همچنین اطلاعات دیباگ مرتبط با آن استفاده می‌کند. نحوه عملکرد کلی آن به شرح زیر است:

هنگامی که دستور داده شود، یک باینری و اطلاعات دیباگ مرتبط با آن خوانده و تحلیل می‌شوند. برای این منظور، libabigail به‌طور پیش‌فرض توضیحات مربوط به نوع‌های داده قابل دسترسی توسط رابط‌ها (توابع و متغیرها) را که از خارج از واحد ترجمه (translation unit) آن‌ها قابل مشاهده هستند، تحلیل می‌کند. پس از انجام این تحلیل، یک پیکره رابط دودویی کاربردی (Application Binary Interface Corpus) تنها با در نظر گرفتن زیرمجموعه‌ای از نوع‌های داده قابل دسترس از رابط‌های مرتبط با نمادهای ELF http://en.wikipedia.org/wiki/Executable_and_Linkable_Format که توسط باینری تعریف و صادر (export) شده‌اند، ساخته می‌شود. این همان پیکره نهایی ABI است که libabigail آن را نماینده ABI باینری تحلیل‌شده در نظر می‌گیرد.

سپس libabigail قابلیت تولید بازنمودهای متنی از پیکره‌های ABI، مقایسه آن‌ها، تحلیل تغییراتشان و گزارش‌دهی درباره آن‌ها را دارد.

abidw [options] [<path-to-elf-file>]

•
--abidiff
بارگذاری ABI باینری ELF داده‌شده در آرگومان، ذخیره آن در قالب XML متعلق به libabigail در یک فایل موقت؛ خواندن مجدد ABI از فایل موقت XML و مقایسه ABI بازخوانی‌شده با ABI باینری ELF ارائه‌شده در آرگومان. دو ABI باید یکسان باشند. اگر یکسان نباشند، برنامه پیامی تشخیصی صادر کرده و با کدی غیرصفر خارج می‌شود.

این گزینه برای دیباگ و سنجش صحت عملکرد (sanity check) است.

  • --abixml-version

    نمایش نسخه قالب ABIXML ارائه‌شده توسط این برنامه و خروج.

  • --add-binaries <bin1,bin2,...>

    به ازای هر یک از باینری‌های جداشده با ویرگول که در آرگومان این گزینه داده شده است، چنانچه باینری در دایرکتوری مشخص‌شده توسط گزینه --added-binaries-dir یافت شود، پیکره ABI آن باینری بارگذاری شده و به مجموعه‌ای از پیکره‌های ABI (با نام گروه پیکره ABI یا ABI Corpus Group) متشکل از باینری مشخص‌شده در آرگومان abidw افزوده می‌شود. سپس آن گروه پیکره سریال‌سازی و خارج می‌شود.

  • --added-binaries-dir | --abd <dir-path>

    این گزینه باید به همراه گزینه‌های --add-binaries، --follow-dependencies یا --list-dependencies به کار رود. باینری‌های فهرست‌شده در آرگومان‌های گزینه --add-binaries، یا باینری‌هایی که وابستگی‌های باینری ورودی هستند (در صورت استفاده از گزینه --follow-dependencies) و در دایرکتوری <dir-path> یافت می‌شوند، به عنوان پیکره ABI بارگذاری شده و به مجموعه پیکره‌های ABI ساخته‌شده و سریال‌سازی‌شده (به نام گروه پیکره ABI) افزوده خواهند شد.

  • --allow-non-exported-interfaces

    هنگام بررسی اطلاعات دیباگ همراه با یک باینری، این ابزار توضیحات مربوط به نوع‌های داده قابل دسترس توسط رابط‌ها (توابع و متغیرها) را که از بیرون واحد ترجمه آن‌ها قابل مشاهده است، تحلیل می‌کند. پس از پایان آن تحلیل، یک پیکره ABI تنها با در نظر گرفتن زیرمجموعه‌ای از نوع‌های داده قابل دسترس از رابط‌های مرتبط با نمادهای ELF http://en.wikipedia.org/wiki/Executable_and_Linkable_Format که توسط باینری تعریف و صادر شده‌اند ساخته می‌شود. این همان پیکره نهایی ABI است که بازنمود متنی آن با نام ABIXML ذخیره می‌گردد.

    با این حال، مشکل این روش این است که تحلیل تمامی رابط‌هایی که از بیرون واحد ترجمه‌شان قابل مشاهده‌اند می‌تواند حجم زیادی داده ایجاد کند، به‌ویژه زمانی که این باینری‌ها برنامه‌های کاربردی باشند (برخلاف کتابخانه‌های اشتراکی). یک نمونه از چنین برنامه‌هایی، هسته لینوکس https://kernel.org است. تحلیل پیکره‌های عظیم ABI مانند این‌ها می‌تواند بسیار کند باشد.

    با این حال در مورد یک باینری با «اندازه معمولی»، با استفاده از این گزینه می‌توان این امکان را فراهم کرد که libabigail تمام رابط‌های قابل مشاهده از خارج از واحد ترجمه‌شان را تحلیل کند.

    توجه داشته باشید که این گزینه به‌طور پیش‌فرض فعال است، مگر اینکه با هسته لینوکس https://kernel.org سر و کار داشته باشیم.

  • --annotate
حاشیه‌نویسی خروجی ABIXML با قرار دادن کامنت‌هایی در بالای بیشتر عناصر. این کامنت‌ها از شکل زیباسازی‌شده (pretty-printed) نوع‌های داده، اعلان‌ها یا حتی نمادهای ELF تشکیل شده‌اند. هدف از این کار، خواناتر کردن خروجی ABIXML برای انسان به منظور دیباگ یا مستندسازی است.
  • --btf

    استخراج اطلاعات ABI از اطلاعات دیباگ BTF https://docs.kernel.org/bpf/btf.html، در صورت وجود در شیء داده‌شده.

  • --check-alternate-debug-info <elf-path>

    چنانچه اطلاعات دیباگ فایل elf-path شامل ارجاعی به یک فایل اطلاعات دیباگ جایگزین <alt-di-label> باشد، abidw بررسی می‌کند که آیا می‌تواند آن فایل اطلاعات دیباگ جایگزین را بیابد یا خیر. در این صورت، پیامی با معنی حاکی از موفقیت صادر کرده و مسیر کامل فایل اطلاعات دیباگ جایگزین یافت‌شده را ذکر می‌کند. در غیر این صورت، یک کد خطا صادر می‌کند.

  • --check-alternate-debug-info-base-name <elf-path>

    همانند --check-alternate-debug-info، اما در پیام موفقیت، تنها نام پایه (base name) فایل اطلاعات دیباگ ذکر می‌شود، نه مسیر کامل آن.

  • --debug-abidiff
مشابه --abidiff اما در حالت دیباگ. در این حالت، برای نوع‌هایی که یکسان‌سازی نوع (type canonicalization) در آن‌ها با شکست مواجه می‌شود، پیام خطا صادر می‌گردد.

این یک گزینه اختیاری برای دیباگ و سنجش صحت عملکرد است. برای فعال‌سازی آن، بسته libabigail باید با گزینه --enable-debug-self-comparison پیکربندی شده باشد.

  • --ctf

    استخراج اطلاعات ABI از اطلاعات دیباگ CTF https://raw.githubusercontent.com/wiki/oracle/binutils-gdb/files/ctf-spec.pdf، در صورت وجود در شیء داده‌شده..IP • 2 --debug-info-dir | -d <dir-path>

    در مواردی که اطلاعات دیباگ برای path-to-elf-file در یک فایل جداگانه قرار دارد که در مکانی غیر استاندارد واقع شده است، این گزینه به abidw اعلام می‌کند که در کجا به دنبال آن فایل اطلاعات دیباگ بگردد.

    توجه داشته باشید که dir-path باید به دایرکتوری ریشه‌ای اشاره کند که اطلاعات دیباگ در زیر آن به صورت درختی مرتب شده‌اند. در سیستم‌های مبتنی بر Red Hat، این دایرکتوری معمولاً <root>/usr/lib/debug است.

    این گزینه می‌تواند چندین بار با دایرکتوری‌های ریشه مختلف مشخص شود. در این صورت، abidw به طور بالقوه تمام آن دایرکتوری‌های ریشه را برای یافتن اطلاعات دیباگ مجزا (split debug info) برای فایل elf جستجو خواهد کرد.

    توجه داشته باشید که این گزینه برای اطلاعات دیباگ مجزایی که توسط مدیر بسته‌ی سیستم شما نصب شده است اجباری نیست، زیرا در آن حالت abidw می‌داند که چگونه آن را پیدا کند.

  • --debug-type-canonicalization | --debug-tc
اشکال‌زدایی فرآیند استانداردسازی انواع (type canonicalization). این کار با استفاده از برابری ساختاری و کانونی (canonical) هنگام استانداردسازی تک‌تک انواع انجام می‌شود. برابری ساختاری و کانونی باید نتیجه یکسانی ارائه دهند. اگر آن‌ها برای یک نوع خاص نتیجه یکسانی نداشته باشند، به این معنی است که استانداردسازی آن نوع دچار خطا شده است. در این صورت، یک پیام خطا صادر شده و اجرای برنامه متوقف می‌شود.

این گزینه تنها در صورتی در دسترس است که بسته با گزینه --enable-debug-type-canonicalization پیکربندی شده باشد.

  • --drop-private-types

    این گزینه به صورت ضمنی توسط گزینه‌های --headers-dir و --header-file فعال می‌شود.

    با این گزینه، انواعی که در هدرها تعریف نشده‌اند به طور کامل از بازنمایی داخلی ایجادشده توسط Libabigail برای بازنمایی ABI حذف می‌شوند و در فایل abi XML قرار نخواهند گرفت.

    این گزینه صرفاً به دلایل سازگاری ارائه شده است و دیگر نباید به طور صریح استفاده شود.

  • --drop-undefined-syms

    با این گزینه، توابع یا متغیرهایی که نماد (صادرشده‌ی) ELF آن‌ها تعریف‌نشده است، از بازنمایی داخلی ایجادشده توسط Libabigail برای بازنمایی ABI حذف می‌شوند و در فایل abi XML قرار نخواهند گرفت.

  • --exported-interfaces-only

    به‌طور پیش‌فرض، هنگام بررسی اطلاعات دیباگ همراه یک باینری، این ابزار توضیحات انواعی را تحلیل می‌کند که از طریق رابط‌ها (توابع و متغیرها) که خارج از واحد ترجمه (translation unit) خود قابل مشاهده هستند، در دسترس قرار دارند. هنگامی که این تحلیل انجام شد، یک پیکره‌ی ABI (ABI corpus) تنها با در نظر گرفتن زیرمجموعه‌ای از انواع ساخته می‌شود که از رابط‌های مرتبط با نمادهای ELF http://en.wikipedia.org/wiki/Executable_and_Linkable_Format که توسط باینری تعریف و صادر (export) شده‌اند، قابل دسترسی هستند. این همان پیکره نهایی ABI است که بازنمایی متنی آن به عنوان ABIXML ذخیره می‌شود.

    با این حال، مشکل این رویکرد آن است که تحلیل تمام رابط‌هایی که از خارج از واحد ترجمه خود قابل مشاهده هستند می‌تواند به حجم بسیار زیادی از داده منجر شود، به خصوص زمانی که آن باینری‌ها بر خلاف کتابخانه‌های اشتراکی، برنامه‌های کاربردی باشند. یک نمونه از این برنامه‌ها هسته لینوکس (Linux Kernel) https://kernel.org است. تحلیل چنین پیکره‌های عظیمی از ABI می‌تواند بسیار کُند باشد.

    برای کاهش این مشکل کارایی، این گزینه به libabigail اجازه می‌دهد تا فقط انواعی را تحلیل کند که از رابط‌های مرتبط با نمادهای تعریف‌شده و صادرشده‌ی ELF http://en.wikipedia.org/wiki/Executable_and_Linkable_Format در دسترس هستند.

    توجه داشته باشید که این گزینه هنگام تحلیل Linux Kernel https://kernel.org به طور پیش‌فرض فعال است. در غیر این صورت، به طور پیش‌فرض غیرفعال است.

  • --fail-no-debug-info

    اگر برنامه نتواند اطلاعات دیباگ را برای باینری ورودی پیدا کند، با یک کد خطای غیر صفر خارج می‌شود. بدون این گزینه، برنامه در صورت عدم وجود اطلاعات دیباگ، اطلاعات ABI مربوط به نمادهای ELF را منتشر می‌کند. در این حالت، اطلاعات نوع (type information) نادیده گرفته می‌شود.

  • --follow-dependencies

    برای هر وابستگیِ باینری ورودیِ abidw، اگر در دایرکتوری مشخص‌شده توسط گزینه --added-binaries-dir یافت شود، یک پیکره ABI از آن وابستگی ایجاد کرده و آن را همراه با پیکره ABI باینری ورودی برنامه، به مجموعه‌ای از پیکره‌های ABI (به نام گروه پیکره ABI یا ABI Corpus Group) اضافه می‌کند. سپس گروه پیکره ABI به صورت سریالی‌شده (serialized) ذخیره می‌شود.

  • --force-early-suppression

    این گزینه باید در کنار گزینه --suppression استفاده شود.

    این گزینه، مشخصات فرونشانی (suppression specifications) <#suppr-spec-label> را مجبور می‌کند تا در حالت فرونشانی زودهنگام (early suppression mode) <#early-suppression-mode-label> اعمال شوند. بنابراین، عناصر بازنمایی داخلی که با مشخصات فرونشانی مطابقت دارند، از حافظه حذف می‌شوند.

    اگر از این گزینه استفاده نشود، تنها مشخصات فرونشانی با ویژگی drop که روی 'yes' <#drop-property-label> تنظیم شده است، مؤثر خواهند بود. سایر دستورالعمل‌های مشخصات فرونشانی به نظر نادیده گرفته می‌شوند.

  • --headers-dir | --hd <headers-directory-path-1>

    مشخص می‌کند که هدرهای عمومی باینری که ابزار باید در نظر بگیرد در کجا قرار دارند. بنابراین ابزار انواعی را که در هدرهای عمومی تعریف نشده‌اند فیلتر می‌کند. این گزینه به‌طور ضمنی گزینه --drop-private-types را فعال می‌کند.

    توجه داشته باشید که می‌توان چندین دایرکتوری هدر عمومی را برای باینری مورد نظر مشخص کرد. در این حالت گزینه --header-dir باید چندین بار در خط فرمان درج شود، مانند مثال زیر:

$ abidw --header-dir /some/path       \
        --header-dir /some/other/path \
        binary > binary.abi
  • --header-file | --hf <header-file-path>

    مشخص می‌کند که یکی از هدرهای عمومی فایل abi که ابزار باید در نظر بگیرد در کجا قرار دارد. بنابراین ابزار انواعی را که در هدرهای عمومی تعریف نشده‌اند فیلتر می‌کند.

    این گزینه به‌طور ضمنی گزینه --drop-private-types را فعال می‌کند.

  • --help | -h

    نمایش یک راهنمای کوتاه درباره دستور و خروج.

  • --kmi-whitelist | --kmi-stablelist |-w <path-to-stablelist>

    هنگام تحلیل یک باینری از Linux Kernel https://kernel.org، این گزینه به فهرست نام نمادهای ELF توابع و متغیرهایی اشاره می‌کند که ABI آن‌ها باید نوشته شود. هر تابع یا متغیری با نامی که در آن فهرست قرار ندارد، نادیده گرفته خواهد شد. این فهرست "فهرست پایدار رابط ماژول هسته" (Kernel Module Interface stable list) نامیده می‌شود. این به این دلیل است که برای هسته، ما از ABI صحبت نمی‌کنیم؛ بلکه بیشتر درباره رابط بین هسته و ماژول‌های آن صحبت می‌کنیم. از این رو اصطلاح KMI به جای KABI به کار می‌رود.

    هر تابع یا متغیر دیگری که نماد ELF آن در آن فهرست پایدار وجود نداشته باشد، توسط فرآیند نگارش KMI در نظر گرفته نخواهد شد.

    اگر این گزینه ارائه نشود -- یعنی اگر هیچ فهرست پایداری مشخص نشده باشد -- تمام KMI، یعنی تمام توابع و متغیرهای سراسریِ عمومی که توسط باینری‌های Linux Kernel https://kernel.org تعریف و صادر شده‌اند، منتشر می‌شوند.

  • --list-dependencies

    برای هر وابستگی از باینری ورودیِ ``abidw``، اگر در دایرکتوری مشخص‌شده توسط گزینه --added-binaries-dir یافت شود، نام آن وابستگی چاپ می‌شود.

  • --load-all-types

    به‌طور پیش‌فرض، libabigail (و در نتیجه abidw) تنها انواعی را بارگذاری می‌کند که از اعلانات توابع و متغیرهایی که به‌طور عمومی توسط باینری تعریف و صادر شده‌اند، قابل دسترسی باشند. بنابراین تنها آن نوع‌ها در خروجی abidw وجود دارند. با این حال، این گزینه باعث می‌شود که abidw تمام انواع تعریف‌شده در باینری‌ها را بارگذاری کند، حتی مواردی را که از اعلانات عمومی قابل دسترسی نیستند.

  • --linux-tree | --lt

    باعث می‌شود abidw مسیر ورودی را به عنوان مسیری به دایرکتوری حاوی باینری vmlinux و چندین باینری ماژول هسته در نظر بگیرد. در این حالت، این برنامه بازنمایی رابط ماژول هسته (KMI) را در خروجی استاندارد منتشر می‌کند.

    در زیر مثالی از کاربرد abidw روی درخت منبع Linux Kernel https://kernel.org آورده شده است.

    ابتدا، یک درخت منبع Linux Kernel https://kernel.org را دریافت کرده و آن را بسازید. سپس ماژول‌های هسته را در یک دایرکتوری نصب کنید. باینری vmlinux را نیز در آن دایرکتوری کپی کنید. و سپس با استفاده از abidw، رابط KMI آن هسته را روی دیسک ذخیره کنید:

$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
$ cd linux && git checkout v4.5
$ make allyesconfig all
$ mkdir build-output
$ make INSTALL_MOD_PATH=./build-output modules_install
$ cp vmlinux build-output/modules/4.5.0
$ abidw --linux-tree build-output/modules/4.5.0 > build-output/linux-4.5.0.kmi
--no-assume-odr-for-cplusplus

هنگام تحلیل یک باینری حاصل از کد C++ با استفاده از اطلاعات دیباگ DWARF http://www.dwarfstd.org، کتابخانه libabigail قاعده یکتایی تعریف (One Definition Rule) https://en.wikipedia.org/wiki/One_Definition_Rule را برای افزایش سرعت تحلیل فرض می‌کند. در این حالت، زمانی که چندین نوع داده در باینری نام یکسانی داشته باشند، همگی برابر فرض می‌شوند.

این گزینه این فرض را غیرفعال کرده و به libabigail دستور می‌دهد تا برای تعیین برابری، انواع داده را واقعاً با یکدیگر مقایسه کند.

  • --no-corpus-path

    صفت مسیر (path) را برای پیکره (corpus) متعلق به ABI صادر نمی‌کند.

  • --no-elf-needed

    فهرست نام‌های وابستگی DT_NEEDED را در پیکره قرار نمی‌دهد.

  • --no-leverage-dwarf-factorization

    هنگام تحلیل باینری‌ای که اطلاعات دیباگ DWARF http://www.dwarfstd.org آن با ابزار DWZ https://sourceware.org/dwz پردازش شده است، فرض می‌شود اطلاعات انواع داده از قبل فاکتورگیری شده‌اند. این زمینه توسط libabigail برای انجام برخی بهینه‌سازی‌های سرعتی به کار گرفته می‌شود.

    این گزینه آن بهینه‌سازی‌ها را غیرفعال می‌کند.

  • --no-load-undefined-interfaces

    به‌طور پیش‌فرض، libabigail (و در نتیجه abidw) اطلاعات مربوط به نمادهای تعریف‌نشده توابع و متغیرها، و همچنین توابع و متغیرهایی که با آن نمادهای تعریف‌نشده مرتبط هستند را بارگذاری می‌کند. به این موارد رابط‌های تعریف‌نشده (undefined interfaces) می‌گویند. با این حال، این گزینه باعث می‌شود که abidw از بارگذاری اطلاعات مربوط به رابط‌های تعریف‌نشده خودداری کند. در نتیجه، فایل XML حاصل حاوی اطلاعاتی در مورد این رابط‌های تعریف‌نشده نخواهد بود.

  • --no-linux-kernel-mode

    بدون این گزینه، اگر abipkgdiff تشخیص دهد باینری‌های در حال بررسی باینری‌های هسته لینوکس هستند (چه vmlinux یا ماژول‌ها)، فقط توابع و متغیرهایی را در نظر می‌گیرد که نمادهای ELF آن‌ها در بخش‌های __ksymtab و __ksymtab_gpl فهرست شده باشند.

    با این گزینه، abipkgdiff باینری را به عنوان یک باینری ELF غیرخاص در نظر می‌گیرد. بنابراین توابع و متغیرهایی را لحاظ می‌کند که به مفهوم ELF تعریف و صادر (export) شده‌اند.

  • --noout

    این گزینه به abidw دستور می‌دهد تا بازنمود XML از ABI را صادر نکند؛ بنابراین تنها اطلاعات ELF و دیباگ را خوانده، ساختار درونی ABI را ایجاد می‌کند و خارج می‌شود. این گزینه معمولاً برای اهداف عیب‌یابی مفید است.

  • --no-parameter-names

    در بازنمود ABI صادرشده، نام پارامترهای تابع نشان داده نمی‌شود و تنها انواع آن‌ها نمایش داده می‌شود.

  • --no-show-locs
در بازنمود ABI صادرشده، فایل، خط یا ستونی که مصنوعات ABI در آن تعریف شده‌اند نشان داده نمی‌شود.
  • --no-write-default-sizes

    در بازنمود XML از ABI، اندازه به بیت (size-in-bits) را برای تعاریف نوع اشاره‌گر، تعاریف نوع ارجاع، اعلان‌های تابع و انواع تابع، در صورتی که با اندازه پیش‌فرض آدرسِ واحد ترجمه برابر باشند، نمی‌نویسد. توجه داشته باشید که libabigail در نسخه‌های پیش از 1.8 اندازه پیش‌فرض را تنظیم نخواهد کرد و انواع بدون صفت size-in-bits را به عنوان اندازه صفر تفسیر می‌کند.

  • --out-file | -o <file-path>

    این گزینه به abidw دستور می‌دهد تا به جای ارسال بازنمود XML از path-to-elf-file به خروجی استاندارد، آن را درون فایل file-path بنویسد.

  • --stats

    آمارهایی درباره موارد گوناگون درونی صادر می‌کند.

  • --suppressions | suppr <path-to-suppression-specifications-file>

    از یک فایل مشخصات فرونشانی <#suppr-spec-label> واقع در path-to-suppression-specifications-file استفاده می‌کند. توجه داشته باشید که این گزینه می‌تواند چندین بار در خط فرمان ظاهر شود. در این صورت، تمام فایل‌های مشخصات فرونشانی ارائه‌شده مد نظر قرار می‌گیرند. مصنوعات ABI منطبق با مشخصات فرونشانی، از خروجی این ابزار حذف می‌شوند.

    تنها مشخصات فرونشانی‌ای که ویژگی drop آن‌ها روی 'yes' <#drop-property-label> تنظیم شده باشد اثرگذار خواهند بود. تمامی دستورالعمل‌های دیگر مشخصات فرونشانی نادیده گرفته می‌شوند، مگر اینکه گزینه خط فرمان --force-early-suppression ارائه شده باشد.

  • --type-id-style <sequence``|``hash>

    این گزینه نحوه شناسایی انواع داده را در فایل‌های XML تولیدشده کنترل می‌کند. سبک پیش‌فرض sequence صرفاً انواع داده را به ترتیبی که با آن‌ها مواجه می‌شود (با پیشوند type-id-) شماره‌گذاری می‌کند. سبک hash از یک درهم‌سازی (پایدار و سازگار) از نام‌های درونی انواع داده در libabigail استفاده می‌کند و هدف آن آسان‌تر کردن مقایسه (diff) فایل‌های XML است.

  • --verbose

    گزارش‌های با جزئیات کامل (verbose) درباره پیشرفت موارد گوناگون درونی صادر می‌کند.

  • --version | -v

    نسخه برنامه را نمایش داده و خارج می‌شود.

1.
تولید یک نمایش ABIXML از یک فایل باینری:
$ abidw binary > binary.abi
2.
تولید یک نمایش ABIXML از مجموعه‌ای از باینری‌های مشخص‌شده در خط فرمان:
$ abidw --added-binaries=bin1,bin2,bin3  \
        --added-binaries-dir /some/where \
        binary > binaries.abi

توجه داشته باشید که باینری‌های bin1، bin2 و bin3 در دایرکتوری /some/where یافت می‌شوند. نمایشی از ABI مجموعه‌ی باینری‌های binary، bin1، bin2 و bin3 تحت عنوان یک ABI corpus group در فایل binaries.abi سریال‌سازی می‌شود.

3.
تولید یک نمایش ABIXML از یک باینری و وابستگی‌های آن:
$ abidw --follow-dependencies              \
        --added-binaries-dir /some/where   \
        binary > binary.abi

توجه داشته باشید که تنها وابستگی‌هایی که در دایرکتوری /some/where قرار دارند تحلیل می‌شوند. ABIهای آن‌ها به همراه ABI باینری با نام binary، در قالب یک ABI corpus group نمایش داده شده و با قالب ABIXML در فایل binary.abi سریال‌سازی می‌شوند.

از نگارش ۴ مشخصات DWARF، اطلاعات اشکال‌زدایی جایگزین http://www.dwarfstd.org/ShowIssue.php?issue=120604.1 یک افزونه‌ی GNU http://www.gnu.org برای مشخصات DWARF به حساب می‌آید. با این حال، پیشنهاد شده است که در نگارش ۵ استاندارد DWARF گنجانده شود. می‌توانید درباره‌ی افزونه‌های GNU برای استاندارد DWARF در اینجا https://fedorahosted.org/elfutils/wiki/DwarfExtensions بیشتر بخوانید.

Dodji Seketeli

2014-2025, Red Hat, Inc.

May 1, 2026