نام (NAME)

addr2line - تبدیل نشانی‌ها یا نماد+آفست به نام فایل و شماره خط

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

addr2line [-a|--addresses]
[-b bfdname|--target=bfdname]
[-C|--demangle[=style]]
[-r|--no-recurse-limit]
[-R|--recurse-limit]
[-e filename|--exe=filename]
[-f|--functions] [-s|--basename]
[-i|--inlines]
[-p|--pretty-print]
[-j|--section=name]
[-H|--help] [-V|--version]
[addr addr ...]

توضیحات (DESCRIPTION)

دستور addr2line نشانی‌ها یا نماد+آفست (symbol+offset) را به نام فایل و شماره خط تبدیل می‌کند. این ابزار با دریافت یک نشانی یا نماد+آفست در یک فایل اجرایی یا یک آفست در بخشی از یک شیء بازآرایی‌پذیر (relocatable object)، با استفاده از اطلاعات اشکال‌زدایی (debugging information) مشخص می‌کند که کدام نام فایل و شماره خط با آن مرتبط هستند.

فایل اجرایی یا شیء بازآرایی‌پذیر مورد استفاده با گزینهٔ -e مشخص می‌شود. پیش‌فرض فایل a.out است. بخشی در شیء بازآرایی‌پذیر که باید استفاده شود با گزینهٔ -j تعیین می‌شود.

دستور addr2line دارای دو حالت کاری است.

در حالت اول، نشانی‌های هگزادسیمال یا نماد+آفست در خط فرمان مشخص می‌شوند و addr2line نام فایل و شماره خط را برای هر نشانی نمایش می‌دهد.

در حالت دوم، addr2line نشانی‌های هگزادسیمال یا نماد+آفست را از ورودی استاندارد می‌خواند و نام فایل و شماره خط را برای هر نشانی در خروجی استاندارد چاپ می‌کند. در این حالت، می‌توان از addr2line در یک لوله (pipe) برای تبدیل نشانی‌های پویا استفاده کرد.

قالب خروجی به‌صورت FILENAME:LINENO است. به‌طور پیش‌فرض هر نشانی ورودی یک خط خروجی تولید می‌کند.

دو گزینه می‌توانند خطوط اضافی قبل از هر خط FILENAME:LINENO (به همان ترتیب) تولید کنند.

اگر از گزینهٔ -a استفاده شود، خطی شامل نشانی ورودی نمایش داده می‌شود.

اگر از گزینهٔ -f استفاده شود، خطی با FUNCTIONNAME نمایش داده می‌شود. این مقدار، نام تابعی است که نشانی را در بر دارد.

یک گزینه می‌تواند خطوط اضافی پس از خط FILENAME:LINENO تولید کند.

اگر از گزینهٔ -i استفاده شود و کد موجود در نشانی داده‌شده به‌دلیل درون‌خطی‌سازی (inlining) توسط کامپایلر در آنجا قرار گرفته باشد، خطوط اضافی پس از آن نمایش داده می‌شوند. برای هر تابع درون‌خطی‌شده، یک یا دو خط اضافی (در صورت استفاده از گزینهٔ -f) نمایش می‌یابد.

به‌عنوان جایگزین، اگر از گزینهٔ -p استفاده شود، هر نشانی ورودی یک خط خروجیِ تکی و بلند شامل نشانی، نام تابع، نام فایل و شماره خط تولید می‌کند. اگر گزینهٔ -i نیز استفاده شده باشد، تمام توابع درون‌خطی‌شده به همین شیوه اما در خطوط جداگانه و با پیشوند (inlined by) نمایش داده می‌شوند.

اگر نام فایل یا نام تابع قابل تشخیص نباشد، addr2line دو علامت سؤال به‌جای آن‌ها چاپ می‌کند. اگر شماره خط قابل تشخیص نباشد، addr2line مقدار 0 را چاپ می‌کند.

هنگام استفاده از symbol+offset، بخش +offset اختیاری است، مگر در حالتی که نماد با یک عدد هگزادسیمال مبهم باشد و اشتباه گرفته شود. نمادهای پردازش‌شده می‌توانند به‌صورت mangled یا unmangled باشند، به استثنای نمادهای unmangled دارای + که مجاز نیستند.

گزینه‌ها (OPTIONS)

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

-a

--addresses

نمایش نشانی پیش از نام تابع، نام فایل و اطلاعات شماره خط. نشانی با پیشوند 0x چاپ می‌شود تا به‌راحتی قابل تشخیص باشد.

-b bfdname

--target=bfdname

قالب کد شیء (object-code format) برای فایل‌های شیء را bfdname تعیین می‌کند.

-C

--demangle[=style]

رمزگشایی (demangle) نام‌های نماد سطح‌پایین به نام‌های سطح کاربر. این گزینه علاوه بر حذف هرگونه زیرخط (underscore) ابتدایی که توسط سیستم اضافه شده، نام توابع ++C را خوانا می‌کند. کامپایلرهای مختلف روش‌های متفاوتی برای mangling دارند. آرگومان اختیاری سبک demangling می‌تواند برای انتخاب شیوهٔ مناسب برای کامپایلر شما استفاده شود.

-e filename

--exe=filename

نام فایل اجرایی که نشانی‌های آن باید ترجمه شوند را مشخص می‌کند. فایل پیش‌فرض a.out است.

-f

--functions

نمایش نام توابع در کنار نام فایل و اطلاعات شماره خط.

-s

--basenames

تنها بخش پایهٔ نام هر فایل (basename) را نمایش می‌دهد.

-i

--inlines

اگر نشانی متعلق به تابعی باشد که درون‌خطی (inlined) شده است، اطلاعات کد منبع برای تمام دامنه‌های دربرگیرنده تا اولین تابع غیر درون‌خطی نیز چاپ خواهد شد. برای مثال، اگر "main" تابع "callee1" را درون‌خطی کند و آن هم "callee2" را درون‌خطی کرده باشد، و نشانی متعلق به "callee2" باشد، اطلاعات منبع برای "callee1" و "main" نیز چاپ خواهد شد.

-j

--section

آفست‌ها را به‌جای نشانی‌های مطلق، به‌صورت نسبی نسبت به بخش (section) مشخص‌شده می‌خواند.

-p

--pretty-print

خروجی را خواناتر و تمیزتر می‌کند: هر موقعیت در یک خط جداگانه چاپ می‌شود. در صورت مشخص شدن گزینهٔ -i، خطوط مربوط به تمام دامنه‌های دربرگیرنده دارای پیشوند (inlined by) خواهند بود.

-r

-R

--recurse-limit

--no-recurse-limit

--recursion-limit

--no-recursion-limit

محدودیت میزان بازگشت (recursion) انجام‌شده هنگام رمزگشایی (demangling) رشته‌ها را فعال یا غیرفعال می‌کند. از آنجا که ساختارهای name mangling امکان بازگشت نامحدود را دارند، ممکن است رشته‌هایی ساخته شوند که رمزگشایی آن‌ها تمام فضای پشته (stack) موجود در رایانهٔ میزبان را مصرف کرده و باعث خطای حافظه شود. این محدودیت تلاش می‌کند با محدود کردن بازگشت به ۲۰۴۸ سطح تو در تو، از بروز این مشکل جلوگیری کند.

به‌طور پیش‌فرض این محدودیت فعال است، اما غیرفعال کردن آن ممکن است برای رمزگشایی نام‌های بسیار پیچیده ضروری باشد. با این حال توجه داشته باشید که با غیرفعال کردن محدودیت بازگشت، احتمال اتمام حافظه پشته وجود دارد و هرگونه گزارش باگ در این رابطه رد خواهد شد.

گزینهٔ -r مترادفی برای گزینهٔ --no-recurse-limit است. گزینهٔ -R مترادفی برای گزینهٔ --recurse-limit است.

توجه داشته باشید که این گزینه تنها در صورتی اثرگذار است که گزینهٔ -C یا --demangle فعال شده باشد.

@file

گزینه‌های خط فرمان را از file می‌خواند. گزینه‌های خوانده‌شده به‌جای گزینهٔ اصلی @file جایگزین می‌شوند. اگر file وجود نداشته باشد یا قابل خواندن نباشد، با گزینه به‌صورت لغوی رفتار شده و حذف نخواهد شد.

گزینه‌ها در file با نویسه‌های فاصله خالی (whitespace) از یکدیگر جدا می‌شوند. یک نویسهٔ فاصله می‌تواند با قرار گرفتن کل گزینه درون گیومهٔ تکی یا دوگانه گنجانده شود. هر نویسه‌ای (از جمله بک‌اسلش) می‌تواند با درج یک پیشوند بک‌اسلش قبل از آن، گنجانده شود. خود file می‌تواند شامل گزینه‌های اضافی @file باشد؛ هرگونه گزینهٔ این‌چنینی به‌صورت بازگشتی پردازش خواهد شد.

همچنین ببینید (SEE ALSO)

مدخل‌های Info برای binutils.

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

حق نشر (c) ۱۹۹۱-۲۰۲۵ بنیاد نرم‌افزارهای آزاد (Free Software Foundation, Inc.)

اجازهٔ کپی، توزیع و/یا تغییر این سند تحت شرایط مجوز مستندات آزاد گنو (GNU Free Documentation License)، نسخهٔ 1.3 یا هر نسخهٔ بالاتر منتشرشده توسط بنیاد نرم‌افزارهای آزاد اعطا می‌شود؛ بدون بخش‌های تغییرناپذیر، بدون متون روی جلد، و بدون متون پشت جلد. یک نسخه از این مجوز در بخشی با عنوان «GNU Free Documentation License» گنجانده شده است.