.\" Man page generated from reStructuredText
.\" by the Docutils 0.22.4 manpage writer.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "ABICOMPAT" "1" "May 01, 2026" "" "Libabigail"
.SH "نام (NAME)"
abicompat \- بررسی سازگاری ABI
.sp
دستور abicompat بررسی می‌کند که آیا برنامه‌ای که با یک کتابخانه مشترک مشخص پیوند خورده است، همچنان با نسخه‌های بعدی آن کتابخانه از نظر ABI سازگار است یا خیر. اگر نسخه جدید کتابخانه ناسازگاری ABI ایجاد کند، abicompat کاربر را راهنمایی کرده و دقیقاً مشخص می‌کند که آن ناسازگاری چیست.
.SH "خلاصه دستور (SYNOPSIS)"
.INDENT 0.0
.INDENT 3.5
.sp
.EX
abicompat [options] [<application> <shared\-library\-first\-version> <shared\-library\-second\-version>]
.EE
.UNINDENT
.UNINDENT
.SH "گزینه‌ها (OPTIONS)"
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
\fB\-\-help\fP
.sp
نمایش راهنمای کوتاهی درباره دستور و خروج.
.IP \(bu 2
\fI\-\-version | \-v\fP
.sp
نمایش نسخه برنامه و خروج.
.IP \(bu 2
\fB\-\-list\-undefined\-symbols | \-u\fP
.sp
نمایش فهرست نمادهای تعریف‌نشده (undefined symbols) برنامه و خروج.
.IP \(bu 2
\fB\-\-show\-base\-names | \-b\fP
.sp
در گزارش نهایی تولیدشده توسط این ابزار، این گزینه باعث می‌شود که به برنامه و کتابخانه‌ها تنها با نام پایه (base name) آنها ارجاع داده شود، نه با نام کامل و مطلق. این قابلیت برای استفاده در اسکریپت‌هایی که قصد مقایسه نام‌های برنامه و کتابخانه‌ها را مستقل از نام دایرکتوری‌های آن‌ها دارند مفید است.
.IP \(bu 2
\fB\-\-app\-debug\-info\-dir | \-\-appd\fP <path\-to\-app\-debug\-info\-directory>
.sp
تنظیم مسیر دایرکتوری‌ای که اطلاعات اشکال‌زدایی برنامه باید در آن قرار داشته باشد. این گزینه برای باینری‌های برنامه‌ای که اطلاعات اشکال‌زدایی آنها در مجموعه‌ای جداگانه از فایل‌ها قرار دارد مفید است.
.IP \(bu 2
\fB\-\-lib\-debug\-info\-dir1 | \-\-libd1\fP <path\-to\-lib1\-debug\-info>
.sp
تنظیم مسیر دایرکتوری‌ای که اطلاعات اشکال‌زدایی نسخه اول کتابخانه مشترک باید در آن قرار داشته باشد. این گزینه برای باینری‌های کتابخانه مشترکی که اطلاعات اشکال‌زدایی آنها در مجموعه‌ای جداگانه از فایل‌ها قرار دارد مفید است.
.IP \(bu 2
\fB\-\-lib\-debug\-info\-dir2 | \-\-libd2\fP <path\-to\-lib1\-debug\-info>
.sp
تنظیم مسیر دایرکتوری‌ای که اطلاعات اشکال‌زدایی نسخه دوم کتابخانه مشترک باید در آن قرار داشته باشد. این گزینه برای باینری‌های کتابخانه مشترکی که اطلاعات اشکال‌زدایی آنها در مجموعه‌ای جداگانه از فایل‌ها قرار دارد مفید است.
.IP \(bu 2
\fB\-\-suppressions | \-\-suppr\fP <\fIpath\-to\-suppressions\fP>
.sp
استفاده از یک فایل مشخصات نادیده‌گیری (suppression specification) \%<#\:suppr-spec-label> واقع در \fIpath\-to\-suppressions\fP\&. توجه داشته باشید که این گزینه می‌تواند چندین بار در خط فرمان تکرار شود؛ در این صورت تمامی فایل‌های مشخصات نادیده‌گیری اعمال خواهند شد.
.IP \(bu 2
\fB\-\-no\-show\-locs\fP
.UNINDENT
.INDENT 0.0
.INDENT 3.5
اطلاعات مربوط به محل تغییر نوع مربوطه در \fIکتابخانه مشترک دوم\fP نمایش داده نشود.
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
\fB\-\-btf\fP
.sp
هنگام مقایسه باینری‌ها، اطلاعات ABI را در صورت وجود از اطلاعات اشکال‌زدایی BTF استخراج کن.
.IP \(bu 2
\fB\-\-ctf\fP
.sp
هنگام مقایسه باینری‌ها، اطلاعات ABI را در صورت وجود از اطلاعات اشکال‌زدایی CTF استخراج کن.
.IP \(bu 2
\fB\-\-fail\-no\-debug\-info\fP
.sp
اگر هیچ اطلاعات اشکال‌زدایی یافت نشد، این گزینه باعث شکست اجرای برنامه می‌شود. در غیر این صورت و بدون این گزینه، برنامه تلاش می‌کند ویژگی‌هایی از باینری‌ها را که وابسته به اطلاعات اشکال‌زدایی نیستند (مانند مشخصات صرفاً ELF) مقایسه کند.
.IP \(bu 2
\fB\-\-ignore\-soname\fP
.sp
نادیده گرفتن تفاوت‌های SONAME هنگام انجام مقایسه.
.IP \(bu 2
\fB\-\-weak\-mode\fP
.sp
این گزینه حالت ضعیف (weak mode) ابزار \fBabicompat\fP را فعال می‌کند. در این حالت، تنها به یک نسخه از کتابخانه نیاز است. به این صورت که abicompat به شکل زیر فراخوانی می‌شود:
.INDENT 2.0
.INDENT 3.5
.sp
.EX
abicompat \-\-weak\-mode <the\-application> <the\-library>
.EE
.UNINDENT
.UNINDENT
.sp
توجه داشته باشید که اگر همراه با برنامه تنها یک نسخه از کتابخانه ارائه شود، حتی می‌توان از گزینه \fB\-\-weak\-mode\fP نیز صرف‌نظر کرد؛ در این حالت، \fBabicompat\fP به طور خودکار به حالت ضعیف تغییر وضعیت می‌دهد:
.INDENT 2.0
.INDENT 3.5
.sp
.EX
abicompat <the\-application> <the\-library>
.EE
.UNINDENT
.UNINDENT
.sp
در این حالت ضعیف، نوع توابع و متغیرهایی که توسط کتابخانه صادر (export) شده و توسط برنامه مصرف می‌شوند (بدین معنی که نمادهای این توابع و متغیرها در برنامه تعریف‌نشده هستند و در کتابخانه تعریف و صادر شده‌اند)، با نسخه‌ای از این نوع‌ها که برنامه انتظار دارد مقایسه می‌شوند. و اگر این دو نسخه از نوع‌ها متفاوت باشند، \fBabicompat\fP تفاوت‌ها را به کاربر نشان می‌دهد.
.sp
به عبارت دیگر، در این حالت، \fBabicompat\fP بررسی می‌کند که تا جایی که به ABI مربوط است، انواع توابع و متغیرهای صادرشده توسط کتابخانه همان معنایی را داشته باشند که برنامه انتظار دارد.
.sp
توجه داشته باشید که در این حالت، \fIabicompat\fP توابع یا متغیرهای (نمادهای) صادرشده‌ای را که برنامه انتظار دارد اما از کتابخانه حذف شده‌اند، تشخیص نمی‌دهد. به همین دلیل به آن حالت \fBضعیف\fP (weak) می‌گویند.
.UNINDENT
.UNINDENT
.UNINDENT
.SH "وضعیت خروج (EXIT STATUS)"
.sp
کد خروج دستور \fBabicompat\fP در صورتی که ABI باینری‌های مورد مقایسه یکسان باشد برابر با 0 است، و در صورتی که متفاوت باشند یا ابزار با خطایی مواجه شود، غیر صفر خواهد بود.
.sp
در حالت دوم، کد خروج یک میدان بیتی ۸ بیتی است که در آن هر بیت معنای خاصی دارد.
.sp
بیت اول، با مقدار 1 و نام \fBABIDIFF_ERROR\fP، به معنای وقوع خطا است.
.sp
بیت دوم، با مقدار 2 و نام \fBABIDIFF_USAGE_ERROR\fP، به این معناست که در نحوه فراخوانی ابزار توسط کاربر خطایی وجود داشته است. برای مثال ممکن است در صورتی تنظیم شود که کاربر ابزار را با یک سوییچ خط فرمان ناشناخته، با تعداد نادرست آرگومان و غیره فراخوانی کرده باشد. اگر این بیت تنظیم شده باشد، بیت \fBABIDIFF_ERROR\fP نیز باید تنظیم باشد.
.sp
بیت سوم، با مقدار 4 و نام \fBABIDIFF_ABI_CHANGE\fP، بدان معناست که ABI باینری‌های مورد مقایسه متفاوت است.
.sp
بیت چهارم، با مقدار 8 و نام \fBABIDIFF_ABI_INCOMPATIBLE_CHANGE\fP، به این معناست که ABI باینری‌های مقایسه‌شده به نحوی ناسازگار تغییر کرده است. اگر این بیت تنظیم شود، بیت \fBABIDIFF_ABI_CHANGE\fP نیز باید تنظیم باشد. اگر \fBABIDIFF_ABI_CHANGE\fP تنظیم شده و \fBABIDIFF_INCOMPATIBLE_CHANGE\fP تنظیم \fIنشده\fP باشد، بدین معناست که ABIهای مقایسه‌شده ممکن است سازگار باشند یا نباشند. در این حالت، یک انسان باید تغییرات ABI را بررسی کند تا در مورد سازگاری یا عدم سازگاری آنها تصمیم بگیرد.
.sp
بیت‌های باقی‌مانده در حال حاضر استفاده نمی‌شوند.
.SH "مثال‌ها (EXAMPLES)"
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
تشخیص یک ناسازگاری احتمالی ABI در نسخه جدیدی از کتابخانه مشترک:
.INDENT 2.0
.INDENT 3.5
.sp
.EX
$ cat \-n test0.h
     1  struct foo
     2  {
     3    int m0;
     4
     5    foo()
     6      : m0()
     7    {}
     8  };
     9
    10  foo*
    11  first_func();
    12
    13  void
    14  second_func(foo&);
    15
    16  void
    17  third_func();
$

$ cat \-n test\-app.cc
     1  // Compile with:
     2  //  g++ \-g \-Wall \-o test\-app \-L. \-ltest\-0 test\-app.cc
     3
     4  #include \(dqtest0.h\(dq
     5
     6  int
     7  main()
     8  {
     9    foo* f = first_func();
    10    second_func(*f);
    11    return 0;
    12  }
$

$ cat \-n test0.cc
     1  // Compile this with:
     2  //  g++ \-g \-Wall \-shared \-o libtest\-0.so test0.cc
     3
     4  #include \(dqtest0.h\(dq
     5
     6  foo*
     7  first_func()
     8  {
     9    foo* f = new foo();
    10    return f;
    11  }
    12
    13  void
    14  second_func(foo&)
    15  {
    16  }
    17
    18  void
    19  third_func()
    20  {
    21  }
$

$ cat \-n test1.h
     1  struct foo
     2  {
     3    int  m0;
     4    char m1; /* <\-\- a new member got added here! */
     5
     6    foo()
     7    : m0(),
     8      m1()
     9    {}
    10  };
    11
    12  foo*
    13  first_func();
    14
    15  void
    16  second_func(foo&);
    17
    18  void
    19  third_func();
$

$ cat \-n test1.cc
     1  // Compile this with:
     2  //  g++ \-g \-Wall \-shared \-o libtest\-1.so test1.cc
     3
     4  #include \(dqtest1.h\(dq
     5
     6  foo*
     7  first_func()
     8  {
     9    foo* f = new foo();
    10    return f;
    11  }
    12
    13  void
    14  second_func(foo&)
    15  {
    16  }
    17
    18  /* Let\(aqs comment out the definition of third_func()
    19     void
    20     third_func()
    21     {
    22     }
    23  */
$
.EE
.UNINDENT
.UNINDENT
.INDENT 2.0
.IP \(bu 2
کامپایل نسخه‌های اول و دوم کتابخانه‌ها:
\fBlibtest\-0.so\fP و \fBlibtest\-1.so\fP:
.INDENT 2.0
.INDENT 3.5
.sp
.EX
$ g++ \-g \-Wall \-shared \-o libtest\-0.so test0.cc
$ g++ \-g \-Wall \-shared \-o libtest\-1.so test1.cc
.EE
.UNINDENT
.UNINDENT
.IP \(bu 2
کامپایل برنامه و پیوند دادن آن با نسخه اول کتابخانه، برای ساخت باینری \fBtest\-app\fP:
.INDENT 2.0
.INDENT 3.5
.sp
.EX
$ g++ \-g \-Wall \-o test\-app \-L. \-ltest\-0.so test\-app.cc
.EE
.UNINDENT
.UNINDENT
.IP \(bu 2
اکنون از \fBabicompat\fP استفاده کنید تا ببینید آیا libtest\-1.so با توجه به ABI نسخه libtest\-0.so، با برنامه سازگاری ABI دارد یا خیر:
.INDENT 2.0
.INDENT 3.5
.sp
.EX
$ abicompat test\-app libtest\-0.so libtest\-1.so
ELF file \(aqtest\-app\(aq might not be ABI compatible with \(aqlibtest\-1.so\(aq due to differences with \(aqlibtest\-0.so\(aq below:
Functions changes summary: 0 Removed, 2 Changed, 0 Added functions
Variables changes summary: 0 Removed, 0 Changed, 0 Added variable

2 functions with some indirect sub\-type change:

  [C]\(aqfunction foo* first_func()\(aq has some indirect sub\-type changes:
    return type changed:
      in pointed to type \(aqstruct foo\(aq:
        size changed from 32 to 64 bits
        1 data member insertion:
          \(aqchar foo::m1\(aq, at offset 32 (in bits)
  [C]\(aqfunction void second_func(foo&)\(aq has some indirect sub\-type changes:
    parameter 0 of type \(aqfoo&\(aq has sub\-type changes:
      referenced type \(aqstruct foo\(aq changed, as reported earlier

$
.EE
.UNINDENT
.UNINDENT
.IP \(bu 2
اکنون از حالت ضعیف abicompat استفاده کنید، یعنی تنها مشخص کردن برنامه و نسخه جدید کتابخانه:
.INDENT 2.0
.INDENT 3.5
.sp
.EX
$ abicompat \-\-weak\-mode test\-app libtest\-1.so
functions defined in library
    \(aqlibtest\-1.so\(aq
have sub\-types that are different from what application
    \(aqtest\-app\(aq
expects:

  function foo* first_func():
    return type changed:
      in pointed to type \(aqstruct foo\(aq:
        size changed from 32 to 64 bits
        1 data member insertion:
          \(aqchar foo::m1\(aq, at offset 32 (in bits)

$
.EE
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SH "نویسندگان (AUTHORS)"
Dodji Seketeli
.SH "کپی‌رایت و تکثیر (COPYRIGHT)"
2014-2025, Red Hat, Inc.
.\" End of generated man page.