نام (NAME)

llvm-ifs - ابزار ساخت جانشین (stub) برای شیء اشتراکی

خلاصه دستور (SYNOPSIS)

llvm-ifs [options] inputs

توضیحات (DESCRIPTION)

دستور llvm-ifs ابزاری است که به‌طور هم‌زمان جانشین‌های متنی انسان‌خوان (فایل‌های .ifs) را برای اشیاء اشتراکی و جانشین‌های شیء اشتراکیِ قابل پیوند (فایل‌های .so) را از روی اشیاء اشتراکی ELF یا جانشین‌های متنی تولید می‌کند. جانشین‌های متنی برای پایش تغییرات ABI در شیء اشتراکی مفید هستند. از جانشین‌های شیء اشتراکی قابل پیوند می‌توان برای جلوگیری از پیوند مجدد (relink) غیرضروری در مواقعی که ABI کتابخانه‌های اشتراکی تغییر نکرده است، استفاده کرد.

قالب‌های IFS (IFS FORMATS)

در ادامه نمونه‌ای از نمایش متنی (IFS) یک شیء اشتراکی تولیدشده توسط llvm-ifs آمده است:

--- !ifs-v1
IFSVersion: 3.0
SoName: libtest.so /* Optional */
Target: x86_64-unknown-linux-gnu   /* Optional, format 1, same format as llvm target triple */
Target: { Arch: x86_64, Endianness: little, Bitwidth: 64 } /* Optional, format 2 */
NeededLibs:
  - libc.so.6
Symbols:
  - { Name: sym0, Type: Notype }
  - { Name: sym1, Type: Object, Size: 0 }
  - { Name: sym2, Type: Func, Weak: false }
  - { Name: sym3, Type: TLS }
  - { Name: sym4, Type: Unknown, Warning: foo }
...

IFSVersion: نسخهٔ فایل IFS برای سازگاری خواننده.
SoName (اختیاری): نام فایل شیء اشتراکی که برای آن جانشین ساخته می‌شود.
Target (اختیاری): اطلاعات معماری، ترتیب بایت‌ها (endianness) و عرض بیتیِ این شیء اشتراکی. این فیلد می‌تواند در قالب صریح یا در قالب ضمنی سه‌گانهٔ (triple) در LLVM باشد. این مورد اختیاری است و می‌توان آن را از طریق گزینه‌های خط فرمان بازنویسی کرد.
NeededLibs: فهرست اشیاء اشتراکی خارجی که این کتابخانه به آن‌ها وابسته است.
Symbols: مجموعه‌ای از تمامی داده‌های مورد نیاز برای پیوند اشیاء برای هر نماد، که بر اساس نام به ترتیب صعودی مرتب شده‌اند.

Name: نام نماد.
Type: مشخص‌کنندهٔ این‌که نماد از نوع شیء (object)، تابع (function)، بدون نوع (no-type)، حافظهٔ محلی رشته (thread local storage) یا ناشناخته (unknown) است. انواع نمادهایی که به‌صراحت پشتیبانی نمی‌شوند، برای بهبود نسبت سیگنال به نویز به عنوان ناشناخته نگاشت می‌شوند.
Size: اندازهٔ نماد مورد نظر؛ برای توابع اعمال نمی‌شود و برای نمادهای NoType اختیاری است.
Undefined: این‌که آیا نماد در این فایل شیء اشتراکی تعریف شده است یا خیر.
Weak: این‌که آیا باید با نماد به عنوان نماد ضعیف (weak) رفتار شود یا خیر.
Warning (اختیاری): متن هشداری که در هنگام پیوند با این نماد در خروجی نمایش داده می‌شود.

این قالب متنی مبتنی بر YAML شامل تمام مواردی است که برای تولید یک شیء اشتراکی ELF قابل پیوند و همچنین یک فایل با قالب Apple TAPI مورد نیاز است. ترتیب نمادها مرتب شده است، بنابراین این فایل‌ها را می‌توان به‌آسانی با استفاده از ابزارهای diff مقایسه کرد. اگر محتوای فایل تغییر کند، نشان‌دهندهٔ یک تغییر بالقوه ناسازگار با ABI (تغییر شکنندهٔ ABI) است.

قالب جانشین ELF (ELF STUB FORMAT)

یک فایل کمینهٔ ELF که می‌تواند توسط پیونددهنده (linker) استفاده شود، باید بخش‌های زیر را به‌درستی مقداردهی کرده باشد:

سرآیند ELF.
سرآیندهای بخش (Section headers).
جدول نمادهای پویا (بخش .dynsym).
جدول رشته‌های پویا (بخش .dynstr).
جدول پویا (بخش .dynamic).

مدخل DT_SYMTAB.
مدخل DT_STRTAB.
مدخل DT_STRSZ.
مدخل‌های DT_NEEDED (اختیاری).
مدخل DT_SONAME (اختیاری).

•: جدول رشته‌های سرآیند بخش (بخش .shstrtab).

این فایل ELF ممکن است با ابزارهای تحلیل ELF که به سرآیندهای برنامه (program headers) اتکا دارند، مشکلات سازگاری داشته باشد. پیونددهنده‌هایی مانند LLD بدون هیچ خطایی با چنین فایل ELF کمینه‌ای کار می‌کنند.

گزینه‌ها (OPTIONS)

--input-format=[IFS|ELF|OtherObjectFileFormats]: تعیین قالب فایل ورودی. در حال حاضر فقط فایل‌های متنی IFS و فایل‌های شیء اشتراکی ELF پشتیبانی می‌شوند. این پرچم اختیاری است، زیرا قالب ورودی می‌تواند به‌طور خودکار استنباط شود.

--output-elf=<output-filename>: تعیین فایل خروجی برای جانشین شیء اشتراکی ELF.

--output-ifs=<output-filename>: تعیین فایل خروجی برای IFS متنی.

--output-tbd=<output-filename>: تعیین فایل خروجی برای Apple TAPI tbd.

--arch=[x86_64|AArch64|...]: این پرچم اختیاری است و فقط باید هنگام خواندن فایل IFS استفاده شود که Arch (معماری) در آن تعریف نشده باشد. این پرچم معماری فایل خروجی را تعیین می‌کند و می‌تواند هر رشته‌ای باشد که توسط فیلد 'e_machine' در ELF پشتیبانی می‌شود. اگر این مقدار با فایل IFS در تعارض باشد، خطایی گزارش شده و اجرای برنامه متوقف می‌شود.

--endianness=[little|big]: این پرچم اختیاری است و فقط باید هنگام خواندن فایل IFS استفاده شود که Endianness در آن تعریف نشده باشد. این پرچم ترتیب بایت‌های فایل خروجی را تعیین می‌کند. اگر این مقدار با فایل IFS در تعارض باشد، خطایی گزارش شده و اجرای برنامه متوقف می‌شود.

--bitwidth=[32|64]: این پرچم اختیاری است و فقط باید هنگام خواندن فایل IFS استفاده شود که BitWidth در آن تعریف نشده باشد. این پرچم عرض بیتیِ فایل خروجی را تعیین می‌کند. اگر این مقدار با فایل IFS ورودی در تعارض باشد، خطایی گزارش شده و اجرای برنامه متوقف می‌شود.

--target=<target triple>;: این پرچم اختیاری است و فقط باید هنگام خواندن فایل IFS استفاده شود که هیچ اطلاعات هدفی در آن تعریف نشده باشد. این پرچم با استفاده از سه‌گانهٔ هدف (target triple) در LLVM، معماری، ترتیب بایت‌ها و عرض بیتی فایل خروجی را تعیین می‌کند. از این پرچم نمی‌توان به‌طور هم‌زمان با سایر پرچم‌های مرتبط با هدف استفاده کرد.

--hint-ifs-target=<target triple>;: این پرچم اختیاری است و فقط باید هنگام خواندن شیء اشتراکی ELF و تولید فایل IFS استفاده شود. به‌طور پیش‌فرض، llvm-ifs از فیلدهای 'Arch، Endianness و BitWidth' برای بازتاب اطلاعات هدف از فایل شیء ورودی استفاده می‌کند. استفاده از این پرچم به llvm-ifs اعلام می‌کند که سه‌گانهٔ هدف مورد انتظار در فایل IFS خروجی چیست. اگر این مقدار با اطلاعات هدف برگرفته از فایل شیء همخوانی داشته باشد، در فیلد 'Target:' فایل IFS تولیدشده قرار می‌گیرد. اگر با فایل شیء ورودی در تعارض باشد، خطایی گزارش شده و اجرای برنامه متوقف خواهد شد.

--hint-ifs-target: این پرچم اختیاری است و فقط باید هنگام خروجی گرفتن فایل IFS استفاده شود. این پرچم فیلد Arch را از فایل IFS حذف می‌کند تا بتوان بعداً آن را بازنویسی کرد.

--strip-ifs-endianness: این پرچم اختیاری است و فقط باید هنگام خروجی گرفتن فایل IFS استفاده شود. این پرچم فیلد Endianness را از فایل IFS حذف می‌کند تا بتوان بعداً آن را بازنویسی کرد.

--strip-ifs-bitwidth: این پرچم اختیاری است و فقط باید هنگام خروجی گرفتن فایل IFS استفاده شود. این پرچم فیلد BitWidth را از فایل IFS حذف می‌کند تا بتوان بعداً آن را بازنویسی کرد.

--strip-ifs-target: این پرچم اختیاری است و فقط باید هنگام خروجی گرفتن فایل IFS استفاده شود. این پرچم فیلد Target را از فایل IFS حذف می‌کند تا بتوان بعداً آن را بازنویسی کرد.

--write-if-changed: هنگامی که این پرچم تنظیم شود، llvm-ifs تنها در صورتی فایل خروجی را می‌نویسد که از پیش وجود نداشته باشد یا محتوای آن با فایل موجود متفاوت باشد.

--strip-size: هنگامی که این پرچم تنظیم شود، llvm-ifs فیلد اندازه (size) را از فایل ifs خروجی حذف خواهد کرد. این ویژگی برای اشیاء اشتراکی مفید است که تنها قصد دارند با کدهای مستقل از موقعیت (position independent code) که نیازی به بازنشانی‌های رونویسی (copy relocations) ندارند پیوند بخورند، یا جاهایی که اندازهٔ یک شیء بخش مفیدی از ABI برای پایش به شمار نمی‌رود.

وضعیت خروج (EXIT STATUS)

در صورت موفقیت، llvm-ifs با مقدار 0 خارج می‌شود. در غیر این صورت، در صورت وقوع خطا، با مقداری غیر صفر خارج خواهد شد.

نویسندگان (AUTHORS)

توسط تیم LLVM نگهداری می‌شود (https://llvm.org).

کپی‌رایت و تکثیر (COPYRIGHT)

2003-2026, LLVM Project

2026-07-15