نام (NAME)

ltrace - ردیاب فراخوانی‌های کتابخانه

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

ltrace [-e filter|-L] [-l|--library=library_pattern] [-x filter] [-S] [-b|--no-signals] [-i] [-w|--where=nr] [-r|-t|-tt|-ttt] [-T] [[-F|--config] pathlist] [-A maxelts] [-s strsize] [-C|--demangle] [-a|--align column] [-n|--indent nr] [-o|--output filename] [-D|--debug mask] [-u username] [-f] [-p pid] [[--] command [arg ...]]

ltrace -c [-e filter|-L] [-l|--library=library_pattern] [-x filter] [-S] [-o|--output filename] [-f] [-p pid] [[--] command [arg ...]]

ltrace -V|--version

ltrace -h|--help

توضیحات (DESCRIPTION)

برنامه ltrace دستور مشخص‌شده (command) را تا زمان پایان یافتن آن اجرا می‌کند. این برنامه فراخوانی‌های کتابخانه‌های پویا را که توسط فرآیندِ در حال اجرا فراخوانده می‌شوند و همچنین سیگنال‌هایی را که آن فرآیند دریافت می‌کند، رهگیری و ثبت می‌نماید. همچنین می‌تواند فراخوانی‌های سیستمی (system calls) اجرا شده توسط برنامه را رهگیری و چاپ کند.

کاربرد آن بسیار شبیه به strace(1) است.

دستور ltrace پارامترهای توابع فراخوانی‌شده و فراخوانی‌های سیستمی را نمایش می‌دهد. برای تعیین اینکه هر تابع چه آرگومان‌هایی دارد، به اعلان‌های خارجی پیش‌نمونه‌های تابع (function prototypes) نیاز دارد. این اعلان‌ها در فایل‌هایی موسوم به کتابخانه‌های پیش‌نمونه (prototype libraries) ذخیره می‌شوند؛ برای جزئیات نحو ساختاری این فایل‌ها، ltrace.conf(5) را ببینید. همچنین برای آگاهی از نحوه یافتن کتابخانه‌های پیش‌نمونه توسط ltrace، بخش کشف کتابخانه پیش‌نمونه (PROTOTYPE LIBRARY DISCOVERY) را مطالعه کنید.

گزینه‌ها (OPTIONS)

-a, --align column

تراز کردن مقادیر بازگشتی در یک ستون (column) مشخص (ستون پیش‌فرض ۵/۸ پهنای صفحه نمایش است).

-A maxelts

حداکثر تعداد عناصر آرایه برای چاپ پیش از خلاصه کردن باقی موارد با سه‌نقطه ("..."). این گزینه همچنین تعداد بسط‌های بازگشتی ساختار را محدود می‌کند.

-b, --no-signals

غیرفعال کردن چاپ سیگنال‌های دریافتی توسط فرآیندِ در حال ردیابی.

-c

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

-C, --demangle

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

-D, --debug mask

نمایش خروجی اشکال‌زدایی خود ltrace. مقدار mask عددی است که مشخص می‌کند کدام پیام‌های اشکال‌زدایی باید نمایش داده شوند. از گزینه -Dh برای مشاهده گزینه‌های قابل استفاده بهره بگیرید، اما توجه داشته باشید که در حال حاضر تنها ماسک اشکال‌زدایی قابل اعتماد ۷۷ است که تمام پیام‌های اشکال‌زدایی را نشان می‌دهد.

-e filter

یک عبارت شرطی که مشخص می‌کند کدام فراخوانی‌های کتابخانه (یعنی فراخوانی‌های انجام‌شده از طریق اسلات‌های PLT، که معمولاً فراخوانی از باینری اصلی به یک کتابخانه یا فراخوانی‌های بین‌کتابخانه‌ای هستند) ردیابی شوند. مثال‌های کاربرد و شرح نحو دستوری در بخش‌های مشخصات فیلتر (FILTER SPECIFICATIONS) و عبارت‌های فیلتر (FILTER EXPRESSIONS) در ادامه آمده است. اگر بیش از یک گزینه -e در خط فرمان مشخص شود، فراخوانی‌های کتابخانه‌ای که با هر یک از آن‌ها تطابق داشته باشند ردیابی می‌شوند. اگر هیچ گزینه -e مشخص نشود، @MAIN به عنوان پیش‌فرض در نظر گرفته می‌شود.

-f

ردیابی فرآیندهای فرزند هنگام ایجاد شدن توسط فرآیندهای در حال ردیابی فعلی در نتیجه فراخوانی‌های سیستمی fork(2) یا clone(2). فرآیند جدید بلافاصله متصل می‌شود.

-F, --config pathlist

شامل فهرستی از مسیرها که با دونقطه (:) از هم جدا شده‌اند. اگر مسیری به یک دایرکتوری اشاره کند، آن دایرکتوری هنگام جستجوی کتابخانه‌های پیش‌نمونه در نظر گرفته می‌شود (بخش کشف کتابخانه پیش‌نمونه (PROTOTYPE LIBRARY DISCOVERY) را ببینید). اگر به یک فایل اشاره کند، آن فایل به‌طور ضمنی در تمام کتابخانه‌های پیش‌نمونه بارگذاری‌شده وارد (import) می‌شود.

-h, --help

نمایش خلاصه‌ای از گزینه‌های ltrace و خروج.

-i

چاپ اشاره‌گر دستورالعمل (instruction pointer) در لحظه فراخوانی کتابخانه.

-l, --library library_pattern

نمایش تنها فراخوانی‌های توابعی که توسط کتابخانه‌های منطبق با library_pattern پیاده‌سازی شده‌اند. این رفتار مشابه آن است که برای هر نمادِ پیاده‌سازی‌شده در کتابخانه مشخص‌شده توسط library_pattern یک گزینه -e تعیین کرده باشید. با تکرار چندباره این گزینه می‌توان الگوهای کتابخانه‌ای متعددی را مشخص کرد. مثال‌های کاربرد و شرح نحو دستوری library_pattern در بخش‌های مشخصات فیلتر (FILTER SPECIFICATIONS) و عبارت‌های فیلتر (FILTER EXPRESSIONS) در ادامه آمده است.

توجه داشته باشید اگرچه این گزینه فراخوانی‌هایی را که ممکن است به سمت کتابخانه‌های انتخاب‌شده هدایت شوند انتخاب می‌کند، اما هیچ تضمین واقعی وجود ندارد که فراخوانی به دلیل مواردی چون LD_PRELOAD یا ترتیب وابستگی‌ها به جای دیگری هدایت نشود. اگر می‌خواهید مطمئن شوید که نمادهای موجود در کتابخانه داده‌شده واقعاً فراخوانی می‌شوند، به جای آن از -x @library_pattern استفاده کنید.

-L

هنگامی که هیچ گزینه -e مشخص نشده باشد، عملکرد پیش‌فرض @MAIN را در نظر نگیر. در عمل این بدان معناست که فراخوانی‌های کتابخانه ردیابی نخواهند شد.

-n, --indent nr

دندانه‌گذاری خروجی ردیابی به اندازه nr فاصله (space) برای هر سطح از تودرتویی فراخوانی‌ها. استفاده از این گزینه، دنبال کردن جریان بصری اجرای برنامه را آسان‌تر می‌کند. این گزینه همچنین توابعی را که هرگز برنمی‌گردند (مانند توابع سرویس برای پرتاب استثناها در محیط زمان اجرای C++)، بدون فایده دندانه‌دار می‌کند.

-o, --output filename

نوشتن خروجی ردیابی در فایل filename به جای خروجی استاندارد خطا (stderr).

-p pid

متصل شدن به فرآیندی با شناسه pid و آغاز ردیابی. این گزینه را می‌توان همراه با تعیین یک دستور برای اجرا نیز به کار برد. امکان اتصال به چند فرآیند با مشخص کردن بیش از یک گزینه -p وجود دارد.

-r

چاپ برچسب زمانی نسبی همراه با هر خط از خروجی ردیابی. این گزینه اختلاف زمانی بین آغاز خطوط متوالی را ثبت می‌کند.

-s strsize

تعیین حداکثر اندازه رشته برای چاپ (پیش‌فرض ۳۲ است).

-S

نمایش فراخوانی‌های سیستمی و همچنین فراخوانی‌های کتابخانه.

-t

افزودن زمان روز به ابتدای هر خط از ردیابی.

-tt

اگر دو بار مشخص شود، زمان چاپ‌شده شامل میکروثانیه نیز خواهد بود.

-ttt

اگر سه بار مشخص شود، زمان چاپ‌شده شامل میکروثانیه خواهد بود و بخش ابتدایی به عنوان تعداد ثانیه‌های سپری‌شده از مبدأ زمانی (epoch) چاپ می‌شود.

-T

نمایش زمان صرف‌شده درون هر فراخوانی. این گزینه اختلاف زمانی بین آغاز و پایان هر فراخوانی را ثبت می‌کند.

-u username

اجرای دستور با شناسه کاربری (userid)، شناسه گروهی (groupid) و گروه‌های تکمیلیِ username. این گزینه تنها هنگام اجرا به عنوان کاربر ریشه (root) سودمند است و اجرای صحیح باینری‌های setuid و/یا setgid را ممکن می‌سازد.

-w, --where nr

نمایش ردگیری پشته (backtrace) به اندازه nr فریم پشته برای هر تابع ردیابی‌شده. این گزینه تنها در صورتی فعال است که پشتیبانی از elfutils یا libunwind در زمان کامپایل فعال شده باشد.

-x filter

یک عبارت شرطی که مشخص می‌کند کدام نقاط ورودی جدول نمادها ردیابی شوند (این موارد معمولاً فراخوانی‌های درون یک کتابخانه یا باینری اصلی هستند، هرچند فراخوانی‌های PLT که توسط -e ردیابی می‌شوند نیز روی نقاط ورودی فرود می‌آیند). مثال‌های کاربرد و شرح نحو دستوری در بخش‌های مشخصات فیلتر (FILTER SPECIFICATIONS) و عبارت‌های فیلتر (FILTER EXPRESSIONS) در ادامه آمده است. اگر بیش از یک گزینه -x در خط فرمان مشخص شود، نمادهایی که با هر یک از آن‌ها تطابق داشته باشند ردیابی می‌شوند. در صورت عدم تعیین -x هیچ نقطه ورودی ردیابی نمی‌شود.

-V, --version

نمایش شماره نگارش ltrace و خروج.

مشخصات فیلتر (FILTER SPECIFICATIONS)

فیلترها با گزینه‌های -l، -e و -x تعیین می‌شوند. به طور خلاصه معنای آن‌ها عبارت است از:

-x یعنی «به من نشان بده چه چیزی این نمادها را فراخوانی می‌کند (شامل فراخوانی‌های محلی)»

-e یعنی «به من نشان بده چه چیزی این نمادها را فراخوانی می‌کند (تنها فراخوانی‌های بین‌کتابخانه‌ای)»

-l یعنی «به من نشان بده چه چیزی به درون این کتابخانه فراخوانی انجام می‌دهد»

فرض کنید کتابخانه‌ای با این سرآیند tstlib.h تعریف شده است:

void func_f_lib(void);
void func_g_lib(void);

و این پیاده‌سازی tstlib.c را دارد:

#include "tstlib.h"
void func_f_lib(void)
{
    func_g_lib();
}
void func_g_lib(void)
{
}

فرض کنید یک فایل اجرایی داریم که از این کتابخانه استفاده می‌کند و در tst.c به این صورت تعریف شده است:

#include "tstlib.h"
void func_f_main(void)
{
}
void main(void)
{
    func_f_main();
    func_f_lib();
}

در صورت پیوند دادن (link) بدون گزینه -Bsymbolic، فراخوانی داخلی func_g_lib() مانند فراخوانی‌های خارجی از PLT استفاده می‌کند و در نتیجه ltrace این خروجی را تولید می‌کند:

$ ltrace -x 'func*' -L ./tst
func_f_main()                             = <void>
func_f_lib@tstlib.so( <unfinished ...>
func_g_lib@tstlib.so()                    = <void>
<... func_f_lib resumed> )                = <void>
+++ exited (status 163) +++

$ ltrace -e 'func*' ./tst
tst->func_f_lib( <unfinished ...>
tstlib.so->func_g_lib()                   = <void>
<... func_f_lib resumed> )                = <void>
+++ exited (status 163) +++

$ ltrace -l tstlib.so ./tst
tst->func_f_lib( <unfinished ...>
tstlib.so->func_g_lib()                   = <void>
<... func_f_lib resumed> )                = <void>
+++ exited (status 163) +++

در مقابل، اگر با -Bsymbolic پیوند داده شود، فراخوانی داخلی func_g_lib() جدول PLT را دور می‌زند و ltrace خروجی زیر را خواهد داد:

$ ltrace -x 'func*' -L ./tst
func_f_main() = <void>
func_f_lib@tstlib.so( <unfinished ...>
func_g_lib@tstlib.so()                    = <void>
<... func_f_lib resumed> )                = <void>
+++ exited (status 163) +++

$ ltrace -e 'func*' ./tst
tst->func_f_lib()                         = <void>
+++ exited (status 163) +++

$ ltrace -l tstlib.so ./tst
tst->func_f_lib()                         = <void>
+++ exited (status 163) +++

عبارت‌های فیلتر (FILTER EXPRESSIONS)

عبارت فیلتر زنجیره‌ای از قواعد مبتنی بر glob یا عبارات باقاعده (regexp) است که برای گزینش نمادها جهت ردیابی از کتابخانه‌های مورد استفاده فرآیند به کار می‌رود. بخش عمده آن شهودی است، بنابراین به عنوان مثال، عبارت زیر فراخوانی‌های malloc و free را ردیابی می‌کند، به جز مواردی که توسط libc انجام می‌شوند:

-e malloc+free-@libc.so*

این عبارت این‌گونه خوانده می‌شود: malloc و free را ردیابی کن، اما هر آنچه را که از libc می‌آید ردیابی نکن. به صورت نیمه‌رسمی، نحو دستوری مثال بالا تقریباً به این شکل است:

{[+-][symbol_pattern][@library_pattern]}

الگوی symbol_pattern برای تطبیق با نام نمادها و library_pattern برای تطبیق با نام‌های SONAME کتابخانه استفاده می‌شود. هر دوی این‌ها به طور ضمنی الگوهای glob هستند، اما می‌توانند عبارات باقاعده نیز باشند (در ادامه ببینید). نحو glob از نویسه‌های ویژه * و ? و کلاس‌های نویسه‌ای، مشابه آنچه که globهای پایه‌ای bash پشتیبانی می‌کنند، پشتیبانی می‌نماید. نویسه‌های ^ و $ به ترتیب برای نشان دادن آغاز و پایان نام داده‌شده شناخته می‌شوند.

هر دو الگوی symbol_pattern و library_pattern باید با کل نام مطابقت داشته باشند. اگر می‌خواهید تنها با بخشی از نام تطبیق داده شود، آن را بر حسب نیاز با یک یا دو علامت * احاطه کنید. استثنا در صورتی است که الگو اصلاً ذکر نشده باشد؛ در این حالت فرض می‌شود که الگوی متناظر * بوده است (بنابراین malloc در واقع همان malloc@* است و @libc.* در واقع همان *@libc.* می‌باشد).

در کتابخانه‌هایی که SONAME مشخصی ندارند، نام پایه (basename) به عنوان SONAME در نظر گرفته می‌شود. این موضوع برای باینری اصلی برنامه نیز صدق می‌کند: /bin/echo دارای SONAME ضمنی echo است. علاوه بر این، الگوی کتابخانه‌ای خاص MAIN همواره با نمادهای باینری اصلی مطابقت دارد و هرگز با کتابخانه‌ای با SONAME واقعی MAIN تطبیق داده نمی‌شود (برای این منظور می‌توانید از ^MAIN یا [M]AIN استفاده کنید).

اگر الگوی نماد یا کتابخانه در میان اسلش قرار گیرد (/مانند این/)، به جای آن به عنوان یک عبارت باقاعده (regular expression) در نظر گرفته می‌شود. به عنوان یک حالت اختصاری، به جای نوشتن /x/@/y/، می‌توانید /x@y/ را بنویسید.

اگر الگوی کتابخانه با اسلش آغاز شود، یک عبارت SONAME نیست، بلکه یک عبارت مسیر (path) است و با نام مسیر کتابخانه مطابقت داده می‌شود.

قاعده نخست ممکن است بدون علامت باشد که در این صورت علامت + فرض می‌شود. از سوی دیگر، اگر قاعده نخست دارای علامت - باشد، همانند آن است که قاعده دیگری به صورت @ پیش از آن وجود داشته است، که اثر آن ردیابی متممِ قاعده داده‌شده خواهد بود.

قواعد فوق برای ساخت مجموعه نمادهای ردیابی‌شده به کار می‌روند. هر نماد کاندید از زنجیره قواعد فوق عبور داده می‌شود. در ابتدا، نماد نشانه‌گذاری‌نشده(unmarked) است. اگر با یک قاعده + مطابقت یابد، نشانه‌گذاری‌شده(marked) می‌شود؛ اگر با یک قاعده - مطابقت یابد، دوباره نشانه‌گذاری‌نشده می‌گردد. اگر پس از اعمال تمام قواعد، نماد نشانه‌گذاری‌شده باقی بماند، ردیابی خواهد شد.

کشف کتابخانه پیش‌نمونه (PROTOTYPE LIBRARY DISCOVERY)

هنگامی که یک کتابخانه در فضای آدرس فرآیندِ در حال ردیابی نگاشت (map) می‌شود، ltrace باید بداند پیش‌نمونه‌های (prototypes) توابعی که این کتابخانه پیاده‌سازی می‌کند چه هستند. برای اهداف ltrace، یک پیش‌نمونه در واقع چیزی فراتر از صرفاً امضای نوع (type signature) است: شامل قالب‌بندی تک‌تک پارامترها و مقدار بازگشتی نیز می‌شود. این پیش‌نمونه‌ها در فایل‌هایی موسوم به «کتابخانه‌های پیش‌نمونه» (prototype libraries) ذخیره می‌شوند.

پس از نگاشت کتابخانه، ltrace نام SONAME آن را پیدا می‌کند. سپس به دنبال فایلی به نام SONAME.conf می‌گردد؛ برای نمونه protolib برای libc.so.6 در فایلی به نام libc.so.6.conf خواهد بود. هنگامی که چنین فایلی یافت شود (توضیحات بیشتر درباره مکان‌های جستجوی این فایل‌ها توسط ltrace در ادامه آمده است)، ltrace تمام پیش‌نمونه‌های ذخیره‌شده در آن را می‌خواند. زمانی که به یک نقطه ورودی جدول نمادها (مانند موارد ردیابی‌شده با -x) برخورد شود، پیش‌نمونه در کتابخانه پیش‌نمونه متناظر با همان کتابخانه‌ای که برخورد در آن رخ داده است جستجو می‌شود. هنگامی که به یک فراخوانی کتابخانه (مانند موارد ردیابی‌شده با -e و -l) برخورد شود، پیش‌نمونه در تمام کتابخانه‌های پیش‌نمونه بارگذاری‌شده برای فرآیند مربوطه جستجو می‌شود. این امر ضروری است زیرا فراخوانی کتابخانه در جدول PLT کتابخانه فراخواننده (caller) ردیابی می‌شود، اما پیش‌نمونه در کتابخانه فراخوانده‌شده (callee) توصیف شده است.

اگر کتابخانه‌ای فاقد SONAME باشد، نام پایه (basename) فایل کتابخانه به جای آن در نظر گرفته می‌شود. برای باینری اصلی برنامه نیز نام پایه در نظر گرفته می‌شود (برای مثال protolib برای bin/echo/ به صورت echo.conf نامیده خواهد شد). اگر نام متناظر با SONAME (مثلاً libc.so.6.conf) پیدا نشود و ماژول تحت بررسی یک کتابخانه اشتراکی باشد، ltrace تطابق‌های جزئی را نیز امتحان می‌کند. ltrace نقطه به نقطه پسوندها را حذف کرده و جستجو را تکرار می‌کند تا اینکه یا یک protolib پیدا شود یا تنها X.so باقی بماند. بنابراین libc.so.conf در نظر گرفته می‌شود، اما libc.conf خیر.

هنگام جستجو برای یک کتابخانه پیش‌نمونه، ltrace به چندین دایرکتوری سر می‌زند. در لینوکس، این مسیرها عبارتند از: $XDG_CONFIG_HOME/ltrace، $HOME/.ltrace، مسیر X/ltrace به ازای هر X در $XDG_CONFIG_DIRS، و /usr/share/ltrace. اگر متغیر محیطی XDG_CONFIG_HOME تعریف نشده باشد، ltrace به جای آن مسیر $HOME/.config/ltrace را بررسی می‌کند.

همچنین سازوکاری برای بارگذاری فایل‌های پیکربندی قدیمی (legacy) وجود دارد. اگر $HOME/.ltrace.conf وجود داشته باشد، در هر کتابخانه پیش‌نمونه بارگذاری‌شده وارد (import) می‌شود. به طور مشابه برای /etc/ltrace.conf. اگر هر دو فایل موجود باشند، هر دو وارد می‌شوند و $HOME/.ltrace.conf پیش از /etc/ltrace.conf مورد مراجعه قرار می‌گیرد.

اگر -F شامل دایرکتوری‌هایی باشد، آن دایرکتوری‌ها با اولویت نسبت به دایرکتوری‌های سیستمی فوق، و با همان ترتیبی که در -F ذکر شده‌اند جستجو می‌شوند. هر فایلی که در -F ارسال شود، مشابه فایل‌های پیکربندی قدیمی بالا و پیش از آن‌ها وارد می‌شود.

برای جزئیات درباره نحو دستوری فایل‌های کتابخانه پیش‌نمونه ltrace، به ltrace.conf(5) مراجعه کنید.

اشکالات (BUGS)

این برنامه بیشتر باگ‌های ذکرشده در strace(1) را دارد.

این ابزار تنها روی لینوکس و در برخی معماری‌ها کار می‌کند.

اگر می‌خواهید اشکالی را گزارش دهید، پیامی به فهرست پستی (ltrace-devel@lists.alioth.debian.org) ارسال کنید، یا در صورتی که از توزیع دبیان گنو/لینوکس استفاده می‌کنید از برنامه reportbug(1) بهره بگیرید.

فایل‌ها (FILES)

/etc/ltrace.conf

فایل پیکربندی سیستم

~/.ltrace.conf

فایل پیکربندی شخصی؛ که بر /etc/ltrace.conf ارجحیت دارد.

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

Juan Cespedes <cespedes@debian.org>
Petr Machata <pmachata@redhat.com>

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

ltrace.conf(5), strace(1), ptrace(2)