.\" -*-nroff-*- .\" Copyright (c) 2012, 2013 Petr Machata, Red Hat Inc. .\" Copyright (c) 1997-2005 Juan Cespedes .\" .\" This program is free software; you can redistribute it and/or .\" modify it under the terms of the GNU General Public License as .\" published by the Free Software Foundation; either version 2 of the .\" License, or (at your option) any later version. .\" .\" This program is distributed in the hope that it will be useful, but .\" WITHOUT ANY WARRANTY; without even the implied warranty of .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU .\" General Public License for more details. .\" .\" You should have received a copy of the GNU General Public License .\" along with this program; if not, write to the Free Software .\" Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA .\" 02110-1301 USA .\" .TH ltrace.conf "5" "October 2012" "" "ltrace configuration file" .SH "نام (NAME)" .LP \fBltrace.conf\fR \- پرونده پیکربندی برای \fBltrace(1)\fR. .SH "توضیحات (DESCRIPTION)" این صفحه راهنما \fBltrace.conf\fR را توصیف می‌کند؛ پرونده‌ای که پیش‌نمونه‌های توابع موجود در باینری‌ها را برای استفاده توسط \fBltrace(1)\fR شرح می‌دهد. دستور \fBltrace\fR برای نمایش آرگومان‌های فراخوانی تابع به این اطلاعات نیاز دارد. هر خط از یک پرونده پیکربندی حداکثر یک مورد را توصیف می‌کند. خطوطی که کاملاً از نویسه‌های فاصله خالی تشکیل شده‌اند نادیده گرفته می‌شوند، همان‌طور که خطوطی که با نویسه نقطه-ویرگول یا هش آغاز می‌شوند (خطوط توضیح) نیز نادیده گرفته می‌شوند. موارد توصیف‌شده می‌توانند پیش‌نمونه‌های توابع، یا تعاریف نام‌های مستعار انواع داده باشند. .SH "پیش‌نمونه‌ها (PROTOTYPES)" یک پیش‌نمونه، نوع مقدار بازگشتی و انواع پارامترهای یک تابع را مشخص می‌کند. نحو ساختار به صورت زیر است: .RS [\fBfunction\fR] \fILENS\fR \fINAME\fR \fB(\fR[\fILENS\fR{,\fILENS\fR}]\fB);\fR .RE \fINAME\fR نام نماد (symbol) است. در حالت ابتدایی، \fILENS\fR به سادگی یک نوع داده است. هم لنزها و هم انواع داده در ادامه توصیف شده‌اند. کلیدواژه \fBfunction\fR در صورت وجود، تأثیری ندارد. می‌توان از آن برای اجبار تفسیر یک خط به عنوان پیش‌نمونه تابع استفاده کرد، هنگامی که نوع بازگشتی کلیدواژه‌ای باشد که ممکن است نوع متفاوتی از خط را شروع کند (مانند \fBimport\fR). برای مثال، یک پیش‌نمونه تابع ساده ممکن است شبیه این باشد: .RS .B int\fR kill\fB(int,int); .RE علیرغم شباهت ظاهری به زبان C، زبان \fBltrace.conf\fR در واقع زبان اختصاصی خود است که فقط تا حدی از C الهام گرفته است. .SH "انواع داده (TYPES)" دستور \fBltrace\fR طیف وسیعی از انواع اولیه را متوجه می‌شود. این‌ها بر اساس قواعد مرسوم C بومی در یک معماری مفروض تفسیر می‌شوند. به عنوان مثال، \fBulong\fR در یک ماشین ۳۲ بیتی GNU/Linux به عنوان عدد صحیح بدون علامت ۴ بایتی، اما در یک ماشین ۶۴ بیتی GNU/Linux به عنوان عدد صحیح بدون علامت ۸ بایتی تفسیر می‌شود. .TP .B void نشان می‌دهد که یک تابع چیزی بازنمی‌گرداند. همچنین می‌تواند برای ایجاد یک اشاره‌گر عمومی استفاده شود؛ یعنی عددی با اندازه اشاره‌گر که در قالب هگزادسیمال قالب‌بندی شده است. .TP .B char کمیت ۸ بیتی که به عنوان یک نویسه ارائه می‌شود. .TP .B ushort,short نشان‌دهنده عدد صحیح کوتاه بدون علامت یا علامت‌دار است. .TP .B uint,int نشان‌دهنده عدد صحیح بدون علامت یا علامت‌دار است. .TP .B ulong,long نشان‌دهنده عدد صحیح بلند بدون علامت یا علامت‌دار است. .TP .B float نشان‌دهنده عدد ممیز شناور با دقت یگانه است. .TP .B double نشان‌دهنده عدد ممیز شناور با دقت مضاعف است. .PP علاوه بر انواع اولیه، انواع مرکب زیر نیز ممکن هستند: .TP .B struct(\fR[\fILENS\fR{,\fILENS\fR}]\fB)\fR یک ساختار با انواع مشخص‌شده به عنوان فیلدها را توصیف می‌کند، مانند \fBstruct(int,int,float)\fR. ترازسازی (Alignment) بر اساس مرسوم در معماری محاسبه می‌شود. ترازسازی سفارشی (مانند packed structs) و فیلدهای بیتی پشتیبانی نمی‌شوند. همچنین برای معماری‌هایی که بین ساختارها و کلاس‌های غیر-POD در ++C تفاوت وجود دارد، امکان تمایز بین آن‌ها وجود ندارد. .TP .B array(\fR\fILENS\fR\fB,\fIEXPR\fR\fB) آرایه‌ای با طول \fIEXPR\fR را توصیف می‌کند که از انواع توصیف‌شده توسط \fILENS\fR تشکیل شده است، مانند \fBarray(int, \fR6\fB)\fR. توجه داشته باشید که در C، آرایه‌ها در نقش آرگومان تابع به اشاره‌گرها تبدیل (decay) می‌شوند. \fBltrace\fR در حال حاضر این مورد را به طور خودکار مدیریت می‌کند، اما برای صحت رسمی کامل، هر چنین آرگومانی باید به عنوان اشاره‌گر به آرایه‌ها توصیف شود. .TP .I LENS\fR\fB* اشاره‌گری به یک نوع داده داده‌شده را توصیف می‌کند، مانند \fBchar*\fR یا \fBint***\fR. توجه داشته باشید که مثال اول در واقع یک اشاره‌گر به یک نویسه را توصیف می‌کند، نه یک رشته. برای لنز \fBstring\fR که برای این موارد کاربرد دارد، به ادامه مراجعه کنید. .SH "لنزها (LENSES)" لنزها نحوه توصیف انواع داده را تغییر می‌دهند. در ساده‌ترین حالت، یک لنز مستقیماً یک نوع داده است. در غیر این صورت یک نوع داده توسط لنز تزیین می‌شود. برنامه \fBltrace\fR لنزهای زیر را متوجه می‌شود: .TP .B bin(\fITYPE\fB) آرگومان، که باید یک نوع عدد صحیح باشد، در مبنای ۲ قالب‌بندی می‌شود. .B oct(\fITYPE\fB) آرگومان، که باید یک نوع عدد صحیح باشد، در مبنای ۸ قالب‌بندی می‌شود. .TP .B hex(\fITYPE\fB) آرگومان، که باید یک نوع عدد صحیح یا ممیز شناور باشد، در مبنای ۱۶ قالب‌بندی می‌شود. آرگومان‌های ممیز شناور به \fBdouble\fR تبدیل شده و سپس با استفاده از اصلاح‌کننده \fB%a\fR در fprintf نمایش داده می‌شوند. .TP .B hide(\fITYPE\fB) آرگومان در فهرست آرگومان‌ها نمایش داده نمی‌شود. .TP .B bool(\fITYPE\fB) آرگومان‌های با مقدار صفر به صورت "false" و سایر مقادیر به صورت "true" نمایش داده می‌شوند. .TP .B bitvec(\fITYPE\fB) آرگومان زیرین به عنوان یک بردار بیتی تفسیر شده و خلاصه‌ای از بیت‌های تنظیم‌شده در بردار نمایش داده می‌شود. به عنوان مثال اگر بیت‌های ۳، ۴، ۵ و ۷ از بردار بیتی تنظیم شده باشند، \fBltrace\fR مقدار <3-5,7> را نشان می‌دهد. بردار بیتی خالی به صورت <> نمایش داده می‌شود. اگر تعداد بیت‌های تنظیم‌شده بیشتر از بیت‌های تنظیم‌نشده باشد، معکوس آن نمایش داده می‌شود: به عنوان مثال ~<0> زمانی که عدد 0xfffffffe نمایش داده می‌شود. بنابراین مجموعه کامل به صورت ~<> نمایش داده می‌شود. اگر نوع زیرین از نوع عدد صحیح باشد، بیت‌ها به ترتیب طبیعی big-endian با بیت کم‌ارزش (LSB) به عنوان بیت ۰ نمایش داده می‌شوند. برای مثال \fBbitvec(ushort)\fR با مقدار 0x0102 صرف‌نظر از ترتیب بایت‌های زیرین، به صورت <1,8> نمایش داده می‌شود. برای سایر انواع داده (به ویژه ساختارها و آرایه‌ها)، داده‌های زیرین بایت به بایت تفسیر می‌شوند. بیت ۰ از بایت اول شماره ۰ دارد، بیت ۰ از بایت دوم شماره ۸ و غیره. بنابراین \fBbitvec(struct(int))\fR به ترتیب بایت‌ها حساس است و بایت‌های تشکیل‌دهنده عدد صحیح را به ترتیب حافظه آن‌ها نشان می‌دهد. اشاره‌گرها ابتدا ارجاع‌زدایی می‌شوند، بنابراین \fBbitvec(array(char, \fR32\fB)*)\fR در واقع یک اشاره‌گر به یک بردار بیتی ۲۵۶ بیتی است. .PP .B string(\fITYPE\fB) .br .B string[\fIEXPR\fB] .br .B string .RS فرم اول آرگومان استاندارد است، و دو فرم دیگر شکر نحوی هستند. در فرم استاندارد، آرگومان تابع به صورت رشته قالب‌بندی می‌شود. \fITYPE\fR می‌تواند هر یک از فرم‌های زیر را داشته باشد: \fIX\fB*\fR، یا \fBarray(\fIX\fB,\fIEXPR\fB)\fR، یا \fBarray(\fIX\fB,\fIEXPR\fB)*\fR. در اینجا \fIX\fR برای رشته‌های عادی \fBchar\fR، یا برای رشته‌های نویسه-عریض یک نوع عدد صحیح است. اگر یک آرایه داده شود، طول آن معمولاً یک عبارت \fBzero\fR خواهد بود (اما اجباری نیست). استفاده از آرگومانی که یک آرایه ساده است (یعنی نه یک اشاره‌گر به آرایه) به عنوان مثال در ساختارهای C، در مواردی مانند \fBstruct(string(array(char, \fR6\fB)))\fR که نوع معادل \fBstruct {char \fRs\fB[\fR6\fB];}\fR در C را توصیف می‌کند، منطقی است. از آنجا که رشته‌های ساده شبیه C بسیار رایج هستند، دو شکل خلاصه وجود دارد. اولین شکل خلاصه (با قلاب) همان معنی \fBstring(array(char, \fIEXPR\fB)*)\fR را دارد. عبارت ساده \fBstring\fR بدون هیچ آرگومانی معادل \fBstring[zero]\fR در نظر گرفته می‌شود. توجه داشته باشید که \fBchar*\fR به خودی خود یک اشاره‌گر به یک char را توصیف می‌کند. برنامه \fBltrace\fR اشاره‌گر را ارجاع‌زدایی کرده و تک نویسه‌ای که به آن اشاره می‌کند را خوانده و نمایش می‌دهد. .RE .B enum(\fINAME\fR[\fB=\fIVALUE\fR]{,\fINAME\fR[\fB=\fIVALUE\fR]}\fB) .br .B enum[\fITYPE\fB]\fB(\fINAME\fR[\fB=\fIVALUE\fR]{,\fINAME\fR[\fB=\fIVALUE\fR]}\fB) .RS این یک لنز شمارشی را توصیف می‌کند. اگر یک آرگومان هر یک از مقادیر مشخص‌شده را داشته باشد، به جای آن به عنوان \fINAME\fR متناظر نشان داده می‌شود. اگر یک \fIVALUE\fR حذف شود، مقدار متوالی بعدی پس از \fIVALUE\fR قبلی در نظر گرفته می‌شود. اگر اولین \fIVALUE\fR حذف شود، به طور پیش‌فرض \fB0\fR است. در صورت ارائه، \fITYPE\fR نوع داده زیرین است. بنابراین می‌توان شمارش‌هایی روی short یا long تعریف کرد\(emآرگومان‌هایی که در C انواع ساده و غیرشمارشی هستند، اما مقادیر آن‌ها را می‌توان به طور معناداری به عنوان شمارش توصیف کرد. در صورت حذف، \fITYPE\fR به صورت \fBint\fR در نظر گرفته می‌شود. .RE .SH "نام‌های مستعار نوع (TYPE ALIASES)" یک خط در پرونده پیکربندی می‌تواند به جای توصیف یک پیش‌نمونه، یک نام مستعار برای نوع داده ایجاد کند. به جای نوشتن همان enum یا struct در جاهای متعدد (و احتمالاً به‌روزرسانی آن در زمان تغییر)، می‌توان نامی برای چنین نوعی معرفی کرد و بعداً فقط از آن نام استفاده کرد: .RS \fBtypedef \fINAME\fB = \fILENS\fB;\fR .RE .SH "دستورالعمل‌های درون‌ریزی (IMPORT DIRECTIVES)" برای پرونده‌های پیکربندی این امکان وجود دارد که تعاریف را از سایر پرونده‌های پیکربندی درون‌ریزی کنند. خطی به شکل: .RS \fBimport "\fIFILENAME\fB";\fR .RE تمامی تعاریف موجود در \fIFILENAME\fR.conf را در پرونده فعلی در دسترس قرار می‌دهد. پرونده درون‌ریزی‌شده در همان دایرکتوری‌هایی جستجو می‌شود که هنگام جستجوی یک پرونده پیکربندی مربوط به یک کتابخانه بررسی می‌شوند؛ برای جزئیات به \fBltrace(1)\fR مراجعه کنید. .SH "ساختارهای بازگشتی (RECURSIVE STRUCTURES)" برنامه \fBltrace\fR به شما امکان می‌دهد ساختارهای بازگشتی را بیان کنید. چنین ساختارهایی تا عمق مشخص‌شده توسط پارامتر \-A باز می‌شوند. برای اعلان یک نوع بازگشتی، ابتدا باید نوع را با استفاده از اعلان پیش‌رو (forward declaration) به \fBltrace\fR معرفی کنید. سپس می‌توانید از آن نوع در سایر تعاریف نوع به روش معمول استفاده کنید: .RS .B typedef \fINAME\fB = struct; .br .B typedef \fINAME\fB = struct(\fINAME\fR can be used here\fB) .RE به عنوان مثال، ساختار پیوندی یگانه زیر و تابعی که چنین فهرستی را به عنوان آرگومان می‌گیرد را در نظر بگیرید: .RS .B typedef\fR int_list \fB= struct; .br .B typedef\fR int_list \fB= struct(int,\fR int_list\fB*); .br .B void\fR ll\fB(\fRint_list\fB*); .RE چنین اعلان‌هایی ممکن است خروجی شبیه به زیر ایجاد کنند: .RS ll({ 9, { 8, { 7, { 6, ... } } } }) = .RE برنامه \fBltrace\fR بازگشت را تشخیص می‌دهد و ساختارهایی را که قبلاً گسترش یافته‌اند دوباره باز نمی‌کند. بنابراین یک فهرست پیوندی دوگانه شبیه زیر خواهد بود: .RS .B typedef\fR int_list \fB= struct; .br .B typedef\fR int_list \fB= struct(int,\fR int_list\fB*,\fR int_list\fB*); .RE با خروجی‌هایی برای مثال مانند: .RS ll({ 9, { 8, { 7, { 6, ..., ... }, recurse^ }, recurse^ }, nil }) .RE نشانه‌های "recurse^" به این معنی هستند که اشاره‌گر داده‌شده به ساختاری اشاره می‌کند که در لایه قبلی باز شده بود. یک "recurse" ساده به این معنی است که به همین شیء اشاره دارد. به عنوان مثال "recurse^^^" یعنی به ساختاری در سه لایه بالاتر اشاره می‌کند. برای یک فهرست پیوندی دوگانه، اشاره‌گر به عنصر قبلی طبیعتاً همان عنصری است که به تازگی در دور قبلی باز شده است، و بنابراین همه آن‌ها یا recurse^ هستند یا nil. اگر اشاره‌گرهای بعدی و قبلی جابجا شوند، خروجی به تناسب تنظیم می‌شود: .RS ll({ 9, nil, { 8, recurse^, { 7, recurse^, { 6, ..., ... } } } }) .RE .SH "عبارت‌ها (EXPRESSIONS)" برنامه \fBltrace\fR از برخی عبارت‌های ابتدایی پشتیبانی می‌کند. هر عبارت می‌تواند یکی از موارد زیر باشد: .TP .I NUM یک عدد صحیح. .TP .B arg\fINUM مقدار آرگومان \fINUM\fR-ام. عبارت دارای همان مقدار آرگومان متناظر است. \fBarg1\fR به آرگومان اول، و \fBarg0\fR به مقدار بازگشتی تابع داده‌شده اشاره دارد. .TP .B retval مقدار بازگشتی تابع، همانند \fBarg0\fR. .TP .B elt\fINUM مقدار عنصر \fINUM\fR-ام از نوع ساختار پیرامونی. به عنوان مثال \fBstruct(ulong,array(int,elt1))\fR ساختاری را توصیف می‌کند که عنصر اول آن یک طول است و عنصر دوم آن آرایه‌ای از intها به همان طول است. .PP .B zero .br .B zero(\fIEXPR\fB) .RS آرایه‌ای را توصیف می‌کند که تا اولین عنصری که هر بایت آن ۰ است امتداد می‌یابد. اگر عبارتی داده شود، آن حداکثر طول آرایه خواهد بود. اگر پایان‌دهنده NUL زودتر پیدا نشود، آرایه در همان نقطه پایان می‌یابد. .RE .SH "بسته‌های پارامتر (PARAMETER PACKS)" گاهی اوقات پیش‌نمونه واقعی تابع بسته به پارامترهای دقیق داده‌شده کمی متفاوت است. به عنوان مثال، تعداد و انواع پارامترهای printf از قبل مشخص نیست، اما ممکن است \fBltrace\fR بتواند آن‌ها را در زمان اجرا تعیین کند. این ویژگی کاربرد وسیع‌تری دارد، اما در حال حاضر تنها بسته پارامتری که \fBltrace\fR پشتیبانی می‌کند، خود رشته قالب به سبک printf است: .TP .B format هنگامی که \fBformat\fR در فهرست پارامترها دیده می‌شود، آرگومان رشته‌ای زیرین تجزیه شده و از مشخص‌کننده‌های قالب به سبک GNU برای تعیین آرگومان‌های واقعی بعدی استفاده می‌شود. به عنوان مثال اگر رشته قالب "%s %d\\n" باشد، گویی \fBformat\fR با \fBstring, string, int\fR جایگزین شده است. .SH "آرگومان‌های بازگشتی (RETURN ARGUMENTS)" توابع C اغلب از یک یا چند آرگومان برای بازگرداندن مقادیر به فراخواننده استفاده می‌کنند. فراخواننده اشاره‌گری به فضای ذخیره‌سازی فراهم می‌کند که تابع فراخوانده‌شده آن را مقداردهی اولیه می‌کند. برنامه \fBltrace\fR پشتیبانی‌هایی برای این الگو دارد. هنگامی که یک باینری در حال ردیابی به یک فراخوانی تابع می‌رسد، \fBltrace\fR ابتدا همه آرگومان‌ها را واکشی می‌کند. سپس بخش \fIچپ\fR از فهرست آرگومان را نمایش می‌دهد. تنها زمانی که تابع بازمی‌گردد، \fBltrace\fR بخش \fIراست\fR را نیز نمایش می‌دهد. معمولاً بخش چپ همه آرگومان‌ها را شامل می‌شود و بخش راست فقط حاوی مقدار بازگشتی است. اما \fBltrace\fR به شما اجازه می‌دهد تا با استفاده از عملگر \fB+\fR که در جلوی یک آرگومان قرار می‌گیرد، دقیقاً محل قرارگیری خط جداکننده را پیکربندی کنید: .RS .B int\fR asprintf\fB(+string*, format); .RE در اینجا، اولین آرگومان به asprintf به عنوان آرگومان بازگشتی مشخص شده است، به این معنی که نمایش کل فهرست آرگومان تا زمان بازگشت تابع به تعویق می‌افتد: .RS a.out->asprintf( .br libc.so.6->malloc(100) = 0x245b010 .br [... more calls here ...] .br <... asprintf resumed> "X=1", "X=%d", 1) = 5 .RE در حال حاضر امکان داشتن یک آرگومان "inout" که اطلاعات را در هر دو جهت منتقل کند وجود ندارد. .SH "مثال‌ها (EXAMPLES)" در ادامه، اولی پیش‌نمونه C و به دنبال آن خط پیکربندی \fBltrace\fR آمده است. .TP .B void\fR func_charp_string\fB(char\fR str\fB[]); .B void\fR func_charp_string\fB(string); .PP .B enum\fR e_foo \fB{\fRRED\fB, \fRGREEN\fB, \fRBLUE\fB}; .br .B void\fR func_enum\fB(enum\fR e_foo bar\fB);\fR .RS .B void\fR func_enum\fB(enum(\fRRED\fB,\fRGREEN\fB,\fRBLUE\fB));\fR .RS \- یا \- .RE .B typedef\fR e_foo \fB= enum(\fRRED\fB,\fRGREEN\fB,\fRBLUE\fB);\fR .br .B void\fR func_enum\fB(\fRe_foo\fB);\fR .RE .TP .B void\fR func_arrayi\fB(int\fR arr\fB[],\fR int len\fB); .B void\fR func_arrayi\fB(array(int,arg2)*,int); .PP .B struct\fR S1 \fB{float\fR f\fB; char\fR a\fB; char \fRb\fB;}; .br .B struct\fR S2 \fB{char\fR str\fB[\fR6\fB]; float\fR f\fB;}; .br .B struct\fR S1 func_struct\fB(int \fRa\fB, struct \fRS2\fB, double \fRd\fB); .RS .B struct(float,char,char)\fR func_struct\fB(int, struct(string(array(char, \fR6\fB)),float), double); .RE .SH "نویسندگان (AUTHORS)" Petr Machata