.\" te -*- nroff -*- .TH STAP 1 .SH "نام (NAME)" stap \- مترجم و راه‌انداز اسکریپت systemtap .\" macros .\" do not nest SAMPLEs .de SAMPLE .br .nr oldin \\n(.i .RS .nf .nh .. .de ESAMPLE .hy .fi .RE .in \\n[oldin]u .. .SH "خلاصه دستور (SYNOPSIS)" .br .B stap [ .I OPTIONS ] .I FILENAME [ .I ARGUMENTS ] .br .B stap [ .I OPTIONS ] .B \- [ .I ARGUMENTS ] .br .B stap [ .I OPTIONS ] .BI \-e " SCRIPT" [ .I ARGUMENTS ] .br .B stap [ .I OPTIONS ] .BI \-l " PROBE" [ .I ARGUMENTS ] .br .B stap [ .I OPTIONS ] .BI \-L " PROBE" [ .I ARGUMENTS ] .br .B stap [ .I OPTIONS ] .B \-\-dump-probe-types .br .B stap [ .I OPTIONS ] .B \-\-dump-probe-aliases .br .B stap [ .I OPTIONS ] .B \-\-dump-functions .SH "توضیحات (DESCRIPTION)" برنامه .IR stap رابط کاربری اصلی ابزار Systemtap است. این برنامه دستورالعمل‌های کاوش نوشته‌شده به یک زبان دامنه-خاص ساده را دریافت کرده، آن‌ها را به کد C ترجمه می‌کند، این کد C را کامپایل کرده و ماژول حاصل را در یک هسته لینوکس در حال اجرا یا تغییردهنده فضای کاربری Dyninst بارگذاری می‌کند تا توابع ردیابی/کاوش درخواستی سیستم را انجام دهد. شما می‌توانید اسکریپت را در یک فایل مشخص (FILENAME)، از ورودی استاندارد (استفاده از \- به‌جای FILENAME)، یا از خط فرمان (با استفاده از \-e SCRIPT) ارائه دهید. برنامه تا زمانی اجرا می‌شود که توسط کاربر متوقف شود، یا اسکریپت به صورت داوطلبانه تابع .I exit() را فراخوانی کند، یا به تعداد کافی خطای نرم رخ دهد. .PP این زبان که در بخش .IR "زبان اسکریپت‌نویسی (SCRIPT LANGUAGE)" در ادامه شرح داده شده است، دارای نوع‌بندی قوی، رسا، بدون نیاز به اعلان متغیرها، رویه‌ای، مناسب برای نمونه‌سازی اولیه، و الهام‌گرفته از .IR awk " و " C است. این زبان امکان پیوند دادن نقاطی از کد منبع یا رویدادهای سیستم را با گرداننده‌ها (handlers) فراهم می‌کند؛ گرداننده‌ها زیرروال‌هایی هستند که به‌صورت همگام اجرا می‌شوند. این مفهوم تا حدودی شبیه به «فهرست دستورات نقطه توقف» در دیباگر .IR gdb است. .SH "بررسی اجمالی مستندات (DOCUMENTATION OVERVIEW)" ابزار systemtap همراه با انواع منابع آموزشی، مستندات و منابع مرجع عرضه می‌شود. این منابع به‌صورت آنلاین و/یا در قالب بسته‌هایی برای استفاده آفلاین در دسترس هستند. برخی از پیام‌های هشدار/خطای تشخیصی systemtap با گنجاندن رشته‌ای مانند \%[man\ error::pass5] صریحاً مطالعه یک صفحه راهنما را پیشنهاد می‌کنند. برای دسترسی به مستندات آنلاین، وب‌سایت پروژه را ببینید: .nh https://sourceware.org/systemtap .hy . .TS tab(%) allbox; l l. \fBصفحات راهنما (man pages)\fP stap (این صفحه)%نحو زبان، مفاهیم، عملیات، گزینه‌ها error::*%توضیحات تکمیلی درباره شرایط خطا warning::*%توضیحات تکمیلی درباره شرایط هشدار stapprobes%نقاط کاوش و متغیرهای زمینه $context آن‌ها stapref%مرجع سریع نحو زبان stappaths%T{ فهرست دایرکتوری‌ها، شامل کتاب‌ها و مراجع T} stap-prep%T{ برنامه نصب وابستگی‌های کمکی مانند debuginfo هسته T} tapset::*%فهرست تولیدشده تپ‌ست‌ها probe::*%فهرست تولیدشده نام‌های مستعار کاوشگر تپ‌ست function::*%فهرست تولیدشده توابع تپ‌ست macro::*%فهرست تولیدشده ماکروهای تپ‌ست stapvars%برخی از متغیرهای سراسری تپ‌ست staprun, stapdyn, stapbpf%برنامه‌های اجرای اسکریپت‌های کامپایل‌شده systemtap systemtap%اسکریپت مقداردهی اولیه (initscript)، کاوش در زمان بوت stap-server%سرور کامپایل stapex%چند مثال اسکریپتی بسیار پایه \fBکتاب‌ها (books)\fP% راهنمای مبتدیان (Beginner's Guide)%کتاب آموزشی، مبانی زبان، مثال‌ها آموزش (Tutorial)%آموزش کوتاه‌تر، تمرین‌ها مرجع زبان (Language Reference)%دفترچه راهنمای تفصیلی زبان، پوشش‌دهنده آمار/تحلیل مرجع تپ‌ست (Tapset Reference)%صفحات راهنمای تپ‌ست که در قالب یک کتاب بازآرایی شده‌اند \fBمراجع (references)\fP% اسکریپت‌های نمونه%T{ بیش از صد ابزار مستقیماً قابل استفاده برای مدیران سیستم، ابزارهای کوچک و ترفندهایی برای یادگیری T} .TE .SH "گزینه‌ها (OPTIONS)" مترجم systemtap از گزینه‌های زیر پشتیبانی می‌کند. هر گزینه دیگری فهرستی از گزینه‌های پشتیبانی‌شده را چاپ می‌کند. گزینه‌ها معمولاً در خط فرمان مشخص می‌شوند. اگر فایل $SYSTEMTAP_DIR/rc وجود داشته باشد، گزینه‌ها از آنجا نیز بارگذاری شده و ابتدا تفسیر می‌شوند. (در صورت عدم تعیین، مقدار پیش‌فرض $SYSTEMTAP_DIR برابر با $HOME/.systemtap خواهد بود.) .PP در برخی موارد، مقدار پیش‌فرض یک گزینه به پیکربندی سیستم خاص بستگی دارد و بنابراین نمی‌توان مستقیماً در اینجا ذکر کرد. در برخی از این موارد اجرای «stap \-\-help» ممکن است مقدار پیش‌فرض را نمایش دهد. .TP .B \- استفاده از ورودی استاندارد به‌جای FILENAME مشخص‌شده به عنوان ورودی زبان کاوش، مگر اینکه \-e SCRIPT ارائه شده باشد. .TP .B \-h \-\-help نمایش پیام راهنما. .TP .B \-V \-\-version نمایش پیام نسخه. .TP .BI \-p " NUM" توقف پس از گذر (pass) شماره NUM. گذرها از ۱ تا ۵ شماره‌گذاری شده‌اند: تجزیه (parse)، بسط (elaborate)، ترجمه (translate)، کامپایل (compile)، اجرا (run). برای جزئیات بخش .B "پردازش (PROCESSING)" را ببینید. .TP .B \-v افزایش سطح پرگویی برای همه گذرها. با هر بار تکرار گزینه، خروجی‌های اطلاعاتی بیشتری تولید می‌شود. .TP .B \-\-vp ABCDE افزایش سطح پرگویی بر مبنای هر گذر. به عنوان مثال، «\-\-vp\ 002» ۲ واحد پرگویی تنها به گذر ۳ اضافه می‌کند. ترکیب «\-v\ \-\-vp\ 00004» ۱ واحد پرگویی برای همه گذرها و ۴ واحد اضافی برای گذر ۵ اضافه می‌کند. .TP .B \-k نگه‌داشتن دایرکتوری موقت پس از اتمام تمامی پردازش‌ها. این کار ممکن است جهت بررسی کد C تولیدشده یا استفاده مجدد از شیء کامپایل‌شده هسته مفید باشد. .TP .B \-g حالت گورو (Guru). فعال‌سازی تجزیه ساختارهای ناامن در سطح متخصص مانند کد C جاسازی‌شده. .TP .B \-P حالت جستجوی مقدمه (Prologue-searching). این گزینه معادل \-\-prologue\-searching=always است. فعال‌سازی روش‌های اکتشافی جهت دور زدن اطلاعات اشکال‌زدایی نادرست برای متغیرهای زمینه $context پارامتر تابع. .TP .B \-u حالت بهینه‌سازی‌نشده. غیرفعال کردن حذف کدهای بلااستفاده و بسیاری از بهینه‌سازی‌های دیگر در طول بسط / ترجمه. .TP .B \-w حالت سرکوب هشدارها. تمام پیام‌های هشدار را غیرفعال می‌کند. .TP .B \-W در نظر گرفتن تمامی هشدارها به عنوان خطا. .TP .BI \-b استفاده از حالت فله‌ای (bulk mode، فایل‌های percpu اختصاصی هر پردازنده) برای انتقال داده از هسته به فضای کاربری. برای ترکیب مجدد آن‌ها در آینده از برنامه .IR stap\-merge استفاده کنید. .TP .B \-i \-\-interactive حالت تعاملی. رابطی را جهت ساخت گام‌به‌گام و تعاملی اسکریپت systemtap فعال می‌کند. .TP .B \-t جمع‌آوری اطلاعات زمان‌بندی درباره تعداد دفعات اجرای کاوشگر و میانگین زمان صرف‌شده در هر نقطه کاوش. همچنین مشتق‌گیری (derivation) را برای هر نقطه کاوش نمایش می‌دهد. .TP .BI \-s " NUM" استفاده از بافرهای NUM مگابایتی برای انتقال داده‌ها از هسته به فضای کاربری به ازای هر پردازنده. مقدار پیش‌فرض ۱۶ مگابایت است، یا در سیستم‌هایی با حافظه کمتر، مقداری کمتر خواهد بود. .TP .BI \-I " DIR" افزودن دایرکتوری داده‌شده به دایرکتوری جستجوی تپ‌ست (tapset). برای جزئیات، شرح گذر ۲ را ببینید. .TP .BI \-D " NAME=VALUE" افزودن دستورالعمل پیش‌پردازنده C به Makefile ماژول. این موارد را می‌توان برای لغو پارامترهای محدودیت شرح داده شده در ادامه استفاده کرد. .TP .BI \-B " NAME=VALUE" در حالت زمان اجرای هسته (kernel-runtime)، افزودن دستورالعمل make داده‌شده به فراخوانی make برای ساخت ماژول هسته. از این موارد می‌توان برای افزودن یا لغو گزینه‌های kconfig استفاده کرد. به عنوان مثال، از .SAMPLE .B \-B CONFIG_DEBUG_INFO=y .ESAMPLE برای افزودن اطلاعات اشکال‌زدایی استفاده کنید. .TP .BI \-B " FLAG" در حالت زمان اجرای dyninst، افزودن پارامتر داده‌شده به CFLAGS کامپایلر که برای ساخت کتابخانه مشترک dyninst استفاده می‌شود. به عنوان مثال، از .SAMPLE .B \-B \-g .ESAMPLE برای افزودن اطلاعات اشکال‌زدایی استفاده کنید. .TP .BI \-a " ARCH" استفاده از حالت کامپایل چندسکویی (cross-compilation) برای معماری هدف داده‌شده. این مورد نیازمند دسترسی به کامپایلر چندسکویی و درخت ساخت هسته است و همراه با گزینه‌های .SAMPLE .BR "\-B CROSS_COMPILE=arch\-tool\-prefix\-" و .BR "\-r /build/tree" .ESAMPLE به کار می‌رود. .TP .BI \-\-modinfo " NAME=VALUE" افزودن جفت نام/مقدار به عنوان فراخوانی ماکروی MODULE_INFO به ماژول تولیدشده. این کار ممکن است برای اطلاع‌رسانی یا لغو بررسی‌های مختلف مرتبط با ماژول در هسته مفید باشد. .TP .BI \-G " NAME=VALUE" هنگام فراخوانی staprun، مقدار متغیر سراسری NAME را به VALUE تنظیم می‌کند. این مورد برای متغیرهای اسکالر اعلان‌شده به‌صورت سراسری در اسکریپت/تپ‌ست اعمال می‌شود. .TP .BI \-R " DIR" جستجوی منابع زمان اجرای systemtap در دایرکتوری مشخص‌شده. مقدار پیش‌فرض DIR را می‌توان با استفاده از «stap \-\-help» مشاهده کرد. .TP .BI \-r " /DIR" ساخت برای هسته در درخت ساخت مشخص‌شده. همچنین می‌تواند با متغیر محیطی .I SYSTEMTAP_RELEASE تنظیم شود. .TP .BI \-r " RELEASE" ساخت برای هسته در درخت ساخت .BR /lib/modules/RELEASE/build . همچنین می‌تواند با متغیر محیطی .I SYSTEMTAP_RELEASE تنظیم شود. .TP .BI \-m " MODULE" استفاده از نام داده‌شده برای ماژول شیء هسته تولیدشده، به‌جای یک نام تصادفی منحصربه‌فرد. ماژول شیء هسته تولیدشده در دایرکتوری جاری کپی می‌شود. .TP .BI \-d " MODULE" افزودن اطلاعات نماد/بازگشت پشته (symbol/unwind) برای ماژول داده‌شده به ماژول شیء هسته. این کار ممکن است امکان ردیابی نمادین را از آن ماژول‌ها/برنامه‌ها فراهم کند، حتی اگر کاوشگر صریحی درون آن‌ها قرار داده نشده باشد. .TP .BI \-\-ldd افزودن اطلاعات نماد/بازگشت پشته برای تمام کتابخانه‌های مشترک فضای کاربری که توسط ldd تشخیص داده شده برای باینری‌های فضای کاربری کاوش‌شده یا فهرست‌شده با گزینه \-d ضروری هستند. هشدار: این کار می‌تواند حجم ماژول‌های کاوشگر را به میزان قابل توجهی افزایش دهد. توجه داشته باشید که این گزینه با ماژول‌های فضای هسته سروکار ندارد؛ در عوض به \-\-all\-modules در ادامه مراجعه کنید. .TP .BI \-\-all\-modules معادل مشخص کردن «\-dkernel» و یک «\-d» برای هر ماژول هسته‌ای که در حال حاضر بارگذاری شده است. هشدار: این کار می‌تواند حجم ماژول‌های کاوشگر را به میزان قابل توجهی افزایش دهد. .TP .BI \-o " FILE" ارسال خروجی استاندارد به فایل مشخص‌شده. در حالت فله‌ای (bulk mode)، فایل‌های percpu با FILE_ (یا با \-F با FILE_cpu) و به دنبال آن شماره پردازنده آغاز می‌شوند. این گزینه از قالب‌های strftime(3) برای FILE پشتیبانی می‌کند. .TP .BI \-c " CMD" شروع کاوشگرها، اجرای CMD، و خروج هنگام پایان CMD. این کار همچنین تأثیر تنظیم target() روی pid آن فرایند را دارد. توجه داشته باشید که بسیاری از انواع کاوشگرها مستقل از این تنظیم فعال می‌شوند. برای تمرکز روی اسکریپت خود، اضافه کردن چیزی شبیه به این را در نظر بگیرید: .SAMPLE probe FOO { if (pid() != target()) next; .... } .ESAMPLE .TP .BI \-x " PID" تنظیم target() روی PID. اسکریپت مستقل از چرخه حیات PID اجرا می‌شود. .TP .BI \-e " SCRIPT" اجرای SCRIPT مشخص‌شده در خط فرمان. .TP .BI \-E " SCRIPT" اجرای SCRIPT مشخص‌شده. این SCRIPT علاوه بر اسکریپت اصلی مشخص‌شده، از طریق \-e یا به عنوان یک فایل اسکریپت اجرا می‌شود. این گزینه را می‌توان برای اجرای چندین اسکریپت تکرار کرد، و می‌توان از آن در حالت فهرست‌بندی (\-l/\-L) استفاده کرد. .TP .BI \-l " PROBE" به‌جای اجرای یک اسکریپت کاوش، صرفاً تمامی نقاط کاوش موجود منطبق با نقطه کاوش تکی داده‌شده را فهرست می‌کند. الگو ممکن است شامل حروف عام (wildcards) و نام‌های مستعار باشد، اما نه چند نقطه کاوش جداشده با کاما. در صورتی که تطابقی وجود نداشته باشد، کد وضعیت فرآیند نشان‌دهنده شکست خواهد بود. .SAMPLE % stap -e 'probe syscall.* { }' [...] % stap -l 'syscall.*' syscall.accept [...] syscall.writev .ESAMPLE .TP .BI \-L " PROBE" مشابه «\-l»، اما نقاط کاوش منطبق به‌همراه متغیرهای زمینه موجود آن‌ها را فهرست می‌کند. وقتی \-v همراه با \-L تنظیم شود، خروجی شامل نقاط کاوش تکراری است که بر اساس آدرس شمارنده برنامه (PC) خود متمایز می‌شوند. .SAMPLE % stap -L 'process("/lib64/libpython*.so.*").mark("*")' process("/usr/lib64/libpython2.7.so.1.0").mark("function__entry") $arg1:long $arg2:long $arg3:long process("/usr/lib64/libpython2.7.so.1.0").mark("function__return") $arg1:long $arg2:long $arg3:long process("/usr/lib64/libpython3.6m.so.1.0").mark("function__entry") $arg1:long $arg2:long $arg3:long process("/usr/lib64/libpython3.6m.so.1.0").mark("function__return") $arg1:long $arg2:long $arg3:long process("/usr/lib64/libpython3.6m.so.1.0").mark("gc__done") $arg1:long process("/usr/lib64/libpython3.6m.so.1.0").mark("gc__start") $arg1:long process("/usr/lib64/libpython3.6m.so.1.0").mark("line") $arg1:long $arg2:long $arg3:long .ESAMPLE .TP .BI \-F بدون گزینه \-o، ماژول را بارگذاری کرده و کاوشگرها را شروع می‌کند، سپس از ماژول جدا می‌شود و اجازه می‌دهد کاوشگرها در حال اجرا باقی بمانند. با گزینه \-o، دستور staprun را در پس‌زمینه به عنوان یک دیمون اجرا کرده و pid آن را نمایش می‌دهد. .TP .BI \-S " size[,N]" حداکثر اندازه فایل خروجی و حداکثر تعداد فایل‌های خروجی را تنظیم می‌کند. اگر اندازه فایل خروجی از .B size مگابایت تجاوز کند، systemtap فایل خروجی را به فایل بعدی تغییر می‌دهد. و اگر تعداد فایل‌های خروجی از .B N بیشتر شود، systemtap قدیمی‌ترین فایل خروجی را حذف می‌کند. می‌توانید آرگومان دوم را حذف کنید. .TP .BI \-T " TIMEOUT" خروج از اسکریپت پس از TIMEOUT ثانیه. .TP .B \-\-skip\-badvars نادیده گرفتن متغیرهای زمینه‌ای که قابل حل نیستند یا در زمان اجرا در دسترس نیستند و جایگزینی آن‌ها با 0، بدون ایجاد خطا. .TP \fB\-\-prologue\-searching\fR[=\fIWHEN\fR] حالت جستجوی مقدمه. فعال‌سازی روش‌های اکتشافی برای دور زدن اطلاعات اشکال‌زدایی نادرست برای متغیرهای زمینه $context پارامتر تابع. مقدار WHEN می‌تواند یکی از «never»، «always» یا «auto» (یعنی فعال بر اساس اکتشاف) باشد. اگر WHEN ذکر نشود، «always» فرض می‌شود. اگر گزینه ذکر نشود، «auto» فرض می‌شود. .TP .B \-\-suppress\-handler\-errors محصور کردن تمامی گرداننده‌های کاوش در بلوکی شبیه به این: .SAMPLE try { ... } catch { next } .ESAMPLE که باعث می‌شود هرگونه خطای زمان اجرا بدون صدا نادیده گرفته شود. خطاهای نادیده‌گرفته‌شده در محدودیت‌های .BR MAXERRORS شمارش نمی‌شوند. در این حالت، محدودیت‌های .BR MAXSKIPPED نیز نادیده گرفته می‌شوند، به‌طوری که خطاهای بسیار و کاوش‌های ردشده متعددی ممکن است در طول اجرای اسکریپت جمع شوند. هرگونه شمارش کلی همچنان در هنگام خاموش شدن گزارش خواهد شد. .TP .BI \-\-compatible " VERSION" سرکوب تغییرات اخیر زبان اسکریپت یا تپ‌ست که با نسخه قدیمی‌تر مشخص‌شده systemtap ناسازگار هستند. این کار ممکن است در صورتی مفید باشد که یک اسکریپت بسیار قدیمی‌تر systemtap در اجرا با شکست مواجه شود. برای جزئیات بیشتر به بخش «منسوخ‌شدگی (DEPRECATION)» مراجعه کنید. .TP .BI \-\-check\-version این گزینه برای بررسی این است که آیا اسکریپت فعال دارای ساختارهایی است که ممکن است مختص نسخه خاصی از systemtap باشند یا خیر. برای جزئیات بیشتر به بخش «منسوخ‌شدگی (DEPRECATION)» مراجعه کنید. .TP .BI \-\-clean\-cache این گزینه ورودی‌های کهنه را از دایرکتوری حافظه موقت (cache) پاکسازی می‌کند. این کار معمولاً پس از اجراهای موفقیت‌آمیز به طور خودکار انجام می‌شود، اما این گزینه پاکسازی را به صورت دستی فعال کرده و سپس خارج می‌شود. برای جزئیات بیشتر درباره محدودیت‌های حافظه موقت به بخش «حافظه موقت (CACHING)» مراجعه کنید. .TP \fB\-\-color\fR[=\fIWHEN\fR], \fB\-\-colour\fR[=\fIWHEN\fR] این گزینه رنگ‌آمیزی پیام‌های خطا را کنترل می‌کند. مقدار WHEN می‌تواند یکی از «never»، «always» یا «auto» (یعنی فعال فقط در صورت اتصال به ترمینال) باشد. اگر WHEN ذکر نشود، «always» فرض می‌شود. اگر گزینه ذکر نشود، «auto» فرض می‌شود. رنگ‌ها را می‌توان با استفاده از متغیر محیطی SYSTEMTAP_COLORS اصلاح کرد. قالب باید به شکل زیر باشد: .nh \fBkey1=val1:key2=val2:key3=val3\fR ...etc. .hy کلیدهای معتبر عبارتند از: .nh "error", "warning", "source", "caret", and "token". .hy مقادیر، پارامتر(های) Select Graphic Rendition (SGR) را تشکیل می‌دهند. برای SGRهایی که ترمینال شما پشتیبانی می‌کند به مستندات آن مراجعه کنید. به عنوان مثال، رنگ‌های پیش‌فرض به این صورت بیان می‌شوند: .nh \fBerror=01;31:warning=00;33:source=00;34:caret=01:token=01\fR. .hy اگر SYSTEMTAP_COLORS وجود نداشته باشد، رنگ‌های پیش‌فرض استفاده خواهند شد. اگر خالی یا نامعتبر باشد، رنگ‌آمیزی خاموش می‌شود. .TP .BI \-\-disable\-cache این گزینه هرگونه استفاده از دایرکتوری حافظه موقت را غیرفعال می‌کند. هیچ فایلی از حافظه موقت خوانده یا در آن نوشته نخواهد شد. .TP .BI \-\-poison\-cache این گزینه با فایل‌های موجود در دایرکتوری حافظه موقت به عنوان فایل‌های نامعتبر رفتار می‌کند. هیچ فایلی از حافظه موقت خوانده نمی‌شود، اما فایل‌های حاصل از این اجرا همچنان در حافظه موقت نوشته خواهند شد. این گزینه به عنوان یک ابزار عیب‌یابی در زمانی که رفتار کش stap نادرست به نظر می‌رسد در نظر گرفته شده است. اگر این کار کمکی کرد، احتمالاً اشکالی در systemtap وجود دارد که توسعه‌دهندگان مایلند آن را گزارش کنید. .TP \fB\-\-privilege\fR[=\fIstapusr\fR | =\fIstapsys\fR | =\fIstapdev\fR] این گزینه به \fIstap\fR دستور می‌دهد تا اسکریپت را برای یافتن ساختارهایی که برای سطح دسترسی مشخص‌شده مجاز نیستند بررسی کند (بخش \fIکاربران غیرممتاز (UNPRIVILEGED USERS)\fR را ببینید). اگر چنین ساختارهایی استفاده شوند، کامپایل با شکست مواجه می‌شود. اگر \fIstapusr\fR یا \fIstapsys\fR هنگام استفاده از سرور کامپایل (گزینه \fI\-\-use\-server\fR را ببینید) مشخص شوند، سرور اسکریپت را بررسی کرده و در صورت موفقیت‌آمیز بودن کامپایل، سرور ماژول هسته حاصل را به صورت رمزنگاری‌شده امضا می‌کند و تأیید می‌کند که استفاده از آن برای کاربران در سطح دسترسی مشخص‌شده ایمن است. اگر \fI\-\-privilege\fR مشخص نشده باشد، \fI\-pN\fR با N < 5 مشخص نشده باشد، و کاربر فراخواننده \fIroot\fR نباشد و عضو گروه \fIstapdev\fR نباشد، آنگاه \fIstap\fR به طور خودکار گزینه مناسب \fI\-\-privilege\fR را به گزینه‌هایی که قبلاً مشخص شده‌اند اضافه می‌کند. .TP .BI \-\-unprivileged این گزینه معادل \fI\-\-privilege=stapusr\fR است. .TP \fB\-\-use\-server\fR[=\fIHOSTNAME\fR[\fI:PORT\fR] | =\fIIP_ADDRESS\fR[\fI:PORT\fR] | =\fICERT_SERIAL\fR] مشخص کردن سرور(های) کامپایل جهت استفاده برای کامپایل و/یا در ترکیب با .I \-\-list\-servers و .I \-\-trust\-servers (در ادامه) برای فهرست‌بندی. اگر هیچ آرگومانی ارائه نشود، مقدار پیش‌فرض در حالت غیرممتاز (به .IR \-\-privilege مراجعه کنید) انتخاب سرورهای سازگار است که به عنوان همتایان SSL و امضاکنندگان ماژول مورد اعتماد بوده و در حال حاضر آنلاین هستند. در غیر این صورت، مقدار پیش‌فرض انتخاب سرورهای سازگار است که به عنوان همتایان SSL مورد اعتماد بوده و آنلاین هستند. گزینه .I \-\-use\-server را می‌توان بیش از یک بار مشخص کرد که در این حالت فهرستی از سرورها به ترتیب مشخص‌شده جمع‌آوری می‌شود. سرورها را می‌توان با نام میزبان، آدرس IP یا شماره سریال گواهی (به دست آمده با استفاده از .IR \-\-list\-servers ) مشخص کرد. مورد اخیر معمولاً هنگام اعطا یا لغو اعتماد به یک سرور استفاده می‌شود (به .I \-\-trust\-servers در ادامه مراجعه کنید). اگر سروری با نام میزبان یا آدرس IP مشخص شده باشد، می‌توان یک شماره پورت اختیاری را نیز تعیین کرد. این برای دسترسی به سرورهایی که در شبکه محلی نیستند یا برای تعیین یک سرور خاص مفید است. آدرس‌های IP می‌توانند آدرس‌های IPv4 یا IPv6 باشند. اگر یک آدرس IPv6 مشخص از نوع پیوند-محلی (link local) باشد و روی بیش از یک رابط وجود داشته باشد، رابط مورد نظر را می‌توان با افزودن علامت درصد (%) و به دنبال آن نام رابط مورد نظر به انتهای آدرس مشخص کرد؛ برای مثال «fe80::5eff:35ff:fe07:55ca%eth0». به منظور تعیین شماره پورت همراه با آدرس IPv6، لازم است آدرس IPv6 را در قلاب‌های مربع ([]) قرار داد تا شماره پورت از بقیه آدرس جدا شود؛ برای مثال «[fe80::5eff:35ff:fe07:55ca]:5000» یا «[fe80::5eff:35ff:fe07:55ca%eth0]:5000». اگر \fI\-\-use\-server\fR مشخص نشده باشد، \fI\-pN\fR با N < 5 مشخص نشده باشد، و کاربر فراخواننده \fIroot\fR نبوده و عضو گروه \fIstapdev\fR نباشد، اما عضو گروه \fIstapusr\fR باشد، آنگاه \fIstap\fR به طور خودکار \fI\-\-use\-server\fR را به گزینه‌هایی که قبلاً مشخص شده‌اند اضافه می‌کند. .TP \fB\-\-use\-server\-on\-error\fR[=\fByes\fR|=\fBno\fR] به stap دستور می‌دهد در صورتی که کامپایل در میزبان محلی به نحوی با شکست مواجه شود که نشان دهد ممکن است با استفاده از سرور موفق شود، کامپایل اسکریپت را با استفاده از یک سرور کامپایل مجدداً امتحان کند. اگر این گزینه مشخص نشود، پیش‌فرض \fIno\fR است. اگر هیچ آرگومانی ارائه نشود، پیش‌فرض \fIyes\fR است. کامپایل مجدد برای انواع خاصی از خطاها (مانند کمبود داده یا منابع) که ممکن است در طول کامپایل مجدد توسط سرور رخ ندهند، تلاش مجدد خواهد شد. سرورهای کامپایل به طور خودکار برای تلاش کامپایل مجدد انتخاب می‌شوند، گویی \fI\-\-use\-server\fR بدون آرگومان مشخص شده باشد. .TP .BI \-\-list\-servers "[=SERVERS]" نمایش وضعیت .IR SERVERS درخواستی، که در آن .I SERVERS فهرستی از ویژگی‌های سرور است که با کاما جدا شده‌اند. فهرست ویژگی‌ها برای فیلتر کردن فهرست سرورهای نمایشی ترکیب می‌شود. ویژگی‌های پشتیبانی‌شده عبارتند از: .RS .TP .BI all تمام سرورهای شناخته‌شده را مشخص می‌کند (همتایان معتمد SSL، امضاکنندگان معتمد ماژول، سرورهای آنلاین). .TP .BI specified سرورهای مشخص‌شده با استفاده از .IR \-\-use\-server را تعیین می‌کند. .TP .BI online خروجی را با حفظ اطلاعات سرورهایی که در حال حاضر آنلاین هستند فیلتر می‌کند. .TP .BI trusted خروجی را با حفظ اطلاعات سرورهایی که به عنوان همتایان SSL مورد اعتماد هستند فیلتر می‌کند. .TP .BI signer خروجی را با حفظ اطلاعات سرورهایی که به عنوان امضاکنندگان ماژول مورد اعتماد هستند فیلتر می‌کند (به .IR \-\-privilege مراجعه کنید). .TP .BI compatible خروجی را با حفظ اطلاعات سرورهایی که با انتشار و معماری فعلی هسته سازگار هستند فیلتر می‌کند. .RE .IP اگر هیچ آرگومانی ارائه نشود، پیش‌فرض .BR specified است. اگر هیچ سروری با استفاده از .IR \-\-use\-server مشخص نشده باشد، سرورهای پیش‌فرض برای .IR \-\-use\-server فهرست می‌شوند. توجه داشته باشید که .IR \-\-list\-servers از سرویس .IR avahi\-daemon برای شناسایی سرورهای آنلاین استفاده می‌کند. اگر این سرویس در دسترس نباشد، .IR \-\-list\-servers در شناسایی سرورهای .IR online ناموفق خواهد بود. برای اینکه .IR \-\-list\-servers بتواند سرورهایی را که به آدرس‌های IPv6 گوش می‌دهند شناسایی کند، فایل پیکربندی .IR /etc/avahi/avahi-daemon.conf مربوط به .IR avahi\-daemon باید شامل یک خط فعال «use-ipv6=yes» باشد. پس از افزودن این خط، سرویس باید ری‌استارت شود تا IPv6 فعال گردد. .TP .BI \-\-trust\-servers "[=TRUST_SPEC]" اعطا یا لغو اعتماد به سرورهای کامپایل مشخص‌شده با .IR \-\-use\-server بر اساس TRUST_SPEC، که در آن TRUST_SPEC فهرستی جداشده با کاما است که نوع اعتماد مورد نظر برای اعطا یا لغو را تعیین می‌کند. عناصر پشتیبانی‌شده عبارتند از: .RS .TP .BI ssl اعتماد به سرورهای مشخص‌شده به عنوان همتایان SSL. .TP .BI signer اعتماد به سرورهای مشخص‌شده به عنوان امضاکنندگان ماژول (به .IR \-\-privilege مراجعه کنید). فقط کاربر ریشه (root) می‌تواند .BR signer را مشخص کند. .TP .BI all\-users اعطای اعتماد به عنوان همتای SSL برای همه کاربران در میزبان محلی. پیش‌فرض این است که اعتماد به عنوان همتای SSL فقط برای کاربر جاری اعطا شود. اعتماد به عنوان امضاکننده ماژول همیشه برای همه کاربران اعطا می‌شود. فقط کاربر ریشه می‌تواند .BR all\-users را مشخص کند. .TP .BI revoke لغو اعتماد مشخص‌شده. پیش‌فرض اعطای آن است. .TP .BI no\-prompt عدم درخواست تأیید از کاربر قبل از انجام عمل درخواستی. پیش‌فرض درخواست تأیید از کاربر است. .RE .IP اگر هیچ آرگومانی ارائه نشود، پیش‌فرض .BR ssl است. اگر هیچ سروری با استفاده از .IR \-\-use\-server مشخص نشده باشد، هیچ اعتمادی اعطا یا لغو نخواهد شد. .IP مگر اینکه \fBno\-prompt\fR مشخص شده باشد، قبل از انجام عملیات از کاربر خواسته می‌شود تا اعطا یا لغو اعتماد را تأیید کند. .TP .BI \-\-sign-module امضای ماژول با MOK (کلید مالک دستگاه - Machine Owner Key) در سیستم‌های UEFI/SecureBoot. برای جزئیات بیشتر بخش «بوت امن (SECUREBOOT)» را ببینید. .TP .BI \-\-dump-probe-types فهرستی از انواع کاوشگرهای پشتیبانی‌شده را تخلیه کرده و خارج می‌شود. اگر .IR \-\-privilege=stapusr نیز مشخص شده باشد، فهرست به انواع کاوشگرهای در دسترس برای کاربران غیرممتاز محدود خواهد شد. .TP .BI \-\-dump-probe-aliases فهرستی از تمام نام‌های مستعار کاوشگر موجود در فایل‌های کتابخانه را تخلیه کرده و خارج می‌شود. .TP .BI \-\-dump-functions فهرستی از تمام توابع عمومی موجود در فایل‌های کتابخانه را به همراه پارامترها و انواع آن‌ها تخلیه کرده و خارج می‌شود. یک تابع از نوع «unknown» نشان‌دهنده تابعی است که مقداری برنمی‌گرداند. توجه داشته باشید که ممکن است همه انواع توابع/پارامترها قابل حل نباشند (این‌ها نیز با «unknown» نشان داده می‌شوند). این ویژگی بسیار نیازمند حافظه است و بنابراین ممکن است در صورت اعمال محدودیت rlimit بر حافظه فرایند توسط سرور هدف (مثلاً از طریق فایل پیکربندی \fI~stap-server/.systemtap/rc\fR، به \fIstap-server\fR(8) مراجعه کنید)، همراه با \fI\-\-use-server\fR به درستی کار نکند. .TP .BI \-\-remote " URL" تنظیم هدف اجرا روی میزبان داده‌شده. این گزینه ممکن است برای تعیین چندین هدف اجرا تکرار شود. گذرهای ۱ تا ۴ به صورت محلی و عادی برای ساخت اسکریپت تکمیل می‌شوند، و سپس گذر ۵ ماژول را در هدف کپی کرده و آن را اجرا می‌کند. قالب‌های قابل قبول URL عبارتند از: .RS .TP \fB[USER@]HOSTNAME\fR, \fBssh://[USER@]HOSTNAME\fR این حالت از ssh استفاده می‌کند، با امکان استفاده اختیاری از نام کاربری متفاوتی نسبت به نام کاربری شما. اگر فایل ssh_config سفارشی در حال استفاده است، عبارت \fBSendEnv LANG\fR را اضافه کنید تا قابلیت بین‌المللی‌سازی حفظ شود. .TP \fBlibvirt://DOMAIN\fR, \fBlibvirt://DOMAIN/LIBVIRT_URI\fR این حالت از \fIstapvirt\fR برای اجرای اسکریپت روی دامنه‌ای که توسط libvirt مدیریت می‌شود استفاده می‌کند. به صورت اختیاری، LIBVIRT_URI را می‌توان برای اتصال به یک درایور خاص و/یا میزبان راه دور مشخص کرد. برای مثال، برای اتصال به درایور ممتاز محلی QEMU، از: .SAMPLE \-\-remote libvirt://MyDomain/qemu:///system .ESAMPLE استفاده کنید. صفحه .nh .hy را برای URIهای پشتیبانی‌شده ببینید. همچنین برای اطلاعات بیشتر درباره نحوه آماده‌سازی دامنه برای کاوش stap به \fIstapvirt\fR(1) مراجعه کنید. .TP \fBunix:PATH\fR این حالت به یک سوکت UNIX متصل می‌شود. این می‌تواند با یک پورت virtio-serial نرم‌افزار QEMU برای اجرای اسکریپت‌ها داخل یک ماشین مجازی در حال اجرا استفاده شود. .TP \fBdirect://\fR حالت حلقه‌بازگشتی (loopback) ویژه برای اجرا روی میزبان محلی. .RE .IP .TP .BI \-\-remote\-prefix افزودن پیشوند «N: » به هر خط خروجی راه دور، که در آن N شاخص هدف اجرای راه دوری است که خط داده‌شده از آن سرچشمه گرفته است. .TP .BI \-\-download\-debuginfo "[=OPTION]" فعال‌سازی، غیرفعال‌سازی یا تنظیم مهلت زمانی برای ویژگی دانلود خودکار debuginfo ارائه‌شده توسط abrt بر اساس OPTION، که در آن OPTION یکی از موارد زیر است: .RS .TP .BI yes فعال‌سازی دانلود خودکار debuginfo بدون مهلت زمانی. این معادل عدم ارائه مقدار OPTION به .IR \-\-download\-debuginfo است. .TP .BI no صریحاً دانلود خودکار debuginfo را غیرفعال می‌کند. این معادل عدم استفاده از این گزینه است. .TP .BI ask نمایش خروجی abrt و درخواست تأیید قبل از ادامه دانلود. هیچ مهلت زمانی تنظیم نخواهد شد. .TP .BI تعیین مهلت زمانی به عنوان یک عدد مثبت برای توقف دانلود در صورتی که بیش از ثانیه طول بکشد. .RE .IP .TP .BI \-\-rlimit-as "=NUM" تعیین حداکثر اندازه حافظه مجازی (فضای آدرس‌دهی) فرایند، به بایت. .TP .BI \-\-rlimit-cpu "=NUM" تعیین محدودیت زمان پردازنده (CPU time)، به ثانیه. .TP .BI \-\-rlimit-nproc "=NUM" تعیین حداکثر تعداد فرایندهایی که می‌توان ایجاد کرد. .TP .BI \-\-rlimit-stack "=NUM" تعیین حداکثر اندازه پشته فرایند، به بایت. .TP .BI \-\-rlimit-fsize "=NUM" تعیین حداکثر اندازه فایل‌هایی که فرایند می‌تواند ایجاد کند، به بایت. .TP .BI \-\-sysroot "=DIR" تعیین دایرکتوری sysroot که فایل‌های هدف (فایل‌های اجرایی، کتابخانه‌ها و غیره) در آن قرار دارند. با \fI\-r RELEASE\fR، دایرکتوری sysroot برای یافتن دایرکتوری مناسب ساخت هسته جستجو می‌شود. با این حال، با \fI\-r /DIR\fR، از sysroot برای یافتن دایرکتوری ساخت هسته استفاده نخواهد شد. .TP .BI \-\-sysenv "=VAR=VALUE" ارائه یک مقدار جایگزین برای یک متغیر محیطی در مواردی که مقدار آن در یک سیستم راه دور متفاوت است. متغیرهای مسیر (مانند PATH، LD_LIBRARY_PATH) در صورت مشخص شدن، به عنوان مسیرهای نسبی به دایرکتوری ارائه‌شده توسط \fI\-\-sysroot\fR در نظر گرفته می‌شوند. .TP .BI \-\-suppress\-time\-limits غیرفعال کردن گزینه‌های مرتبط با \-DSTP_OVERLOAD و همچنین \-DMAXACTION و \-DMAXTRYLOCK. این گزینه نیازمند حالت گورو (guru mode) است. .TP .BI \-\-runtime "=MODE" تنظیم حالت زمان اجرای گذر ۵. گزینه‌های معتبر عبارتند از \fIkernel\fR (پیش‌فرض)، \fIdyninst\fR و \fIbpf\fR. برای اطلاعات بیشتر بخش .BR "زمان‌های اجرای جایگزین (ALTERNATE RUNTIMES)" در ادامه را ببینید. .TP .BI \-\-dyninst حالت خلاصه برای \fI\-\-runtime=dyninst\fR. .TP .BI \-\-bpf حالت خلاصه برای \fI\-\-runtime=bpf\fR. .TP .BI \-\-save-uprobes در ماشین‌هایی که نیاز دارند SystemTap ماژول uprobes خود را بسازد (هسته‌های پیش از نسخه ۳.۵)، این گزینه به SystemTap دستور می‌دهد که یک نسخه از ماژول را در دایرکتوری جاری نیز ذخیره کند (ابتدا یک دایرکتوری جدید به نام «uprobes» ایجاد می‌کند). .TP .BI \-\-target-namespaces "=PID" امکان تنظیم مجموعه‌ای از فضاهای نام هدف را بر اساس فضاهای نامی که PID داده‌شده در آن قرار دارد فراهم می‌کند. این برای توابع تپ‌ست آگاه از فضای نام است. اگر فضاهای نام هدف تنظیم نشده باشند، هدف به صورت پیش‌فرض فضاهای نام فرایند stap خواهد بود. .TP .BI \-\-monitor "=INTERVAL" رابطی را برای نمایش اطلاعات وضعیت ماژول (زمان بالا بودن یا uptime، نام ماژول، شناسه کاربر فراخواننده یا uid، اندازه‌های حافظه، متغیرهای سراسری، فهرست کاوشگرها به همراه آمار آن‌ها) فعال می‌کند. یک آرگومان اختیاری INTERVAL را می‌توان برای تنظیم نرخ نوسازی پنجره وضعیت به ثانیه ارائه کرد. ماژول را می‌توان با فهرستی از دستورات با استفاده از کلیدهای زیر نیز کنترل کرد: .RS .TP .BI c تمام متغیرهای سراسری را به مقادیر اولیه خود بازنشانی می‌کند یا اگر مقدار اولیه نداشتند آن‌ها را صفر می‌کند. .TP .BI s ویژگی استفاده‌شده برای مرتب‌سازی فهرست کاوشگرها را می‌چرخاند. .TP .BI t اعلانی را باز می‌کند تا امکان روشن/خاموش کردن کاوشگرها بر اساس شاخص فراهم شود. نقاط کاوش همچنان تحت تأثیر شرایط خود هستند. .TP .BI r اسکریپت را با روشن کردن تمام کاوشگرها از سر می‌گیرد. .TP .BI p اسکریپت را با خاموش کردن تمام کاوشگرها متوقف می‌کند (pause). .TP .BI x پنجره وضعیت را پنهان/نمایان می‌کند. این امکان مشاهده خروجی بیشتری را فراهم می‌کند. .TP .BI navigation-keys کلیدهای ناوبری را می‌توان برای پیمایش به بالا و پایین پنجره‌ها استفاده کرد. .TP .BI Tab تغییر پیمایش میان پنجره‌های وضعیت و خروجی. .RE .TP .BI \-\-example این گزینه برای اجرای اسکریپت‌های نمونه بدون نیاز به وارد کردن مسیر کامل اسکریپت استفاده می‌شود. اسکریپت‌های نمونه را می‌توان در دایرکتوری مشخص‌شده در صفحه راهنمای .IR stappaths (7) یافت. .TP .BI \-\-no-global-var-display این گزینه برای غیرفعال کردن ثبت خودکار متغیرهای سراسری بدون استفاده در پایان نشست stap استفاده می‌شود. .TP .B \-\-language\-server حالت کارساز زبان (Language server). راه‌اندازی یک سرور زبان که از طریق stdio ارتباط برقرار می‌کند. سرور زبان به سطح پرگویی stap احترام می‌گذارد. .TP .B \-\-build\-as اجرای گذرهای ۱ تا ۴ تحت کاربر مشخص‌شده برای افزایش ایمنی. این رویکرد ممکن است محدودیت‌هایی داشته باشد. کاربران غیرممتاز ممکن است به kallsyms یا /proc دسترسی نداشته باشند. در زمان نصب RPM، کاربر stapunpriv ایجاد می‌شود، بنابراین می‌توان stap را با \-\-build\-as=stapunpriv فراخوانی کرد. .SH "آرگومان‌ها (ARGUMENTS)" هرگونه آرگومان اضافی در خط فرمان برای جایگزینی به تجزیه‌کننده اسکریپت منتقل می‌شود. به ادامه مراجعه کنید. .SH "زبان اسکریپت‌نویسی (SCRIPT LANGUAGE)" زبان اسکریپت‌نویسی systemtap شبیه به .IR awk " و " C است. دو ساختار بیرونی اصلی وجود دارد: کاوشگرها و توابع. در درون این‌ها، دستورات و عبارات از نحو و اولویت عملگرهای مشابه C استفاده می‌کنند. .SS "نحو عمومی (GENERAL SYNTAX)" فاصله‌های خالی نادیده گرفته می‌شوند. سه شکل از توضیحات پشتیبانی می‌شوند: .RS .br .BR # " ... سبک شل، تا پایان خط، به جز $# و @#" .br .BR // " ... سبک ++C، تا پایان خط" .br .BR /* " ... سبک C ... " */ .RE مقدارهای ثابت یا رشته‌هایی هستند که در دو علامت نقل‌قول محصور شده‌اند (همراه با کدهای گریز معمول C با بک‌اسلش، و چسبانده شدن رشته‌های متنی مجاور به یکدیگر، دقیقاً مانند C)، یا اعداد صحیح (در مبنای ده‌دهی، شانزده‌شانزدهی، یا هشت‌هشتی، با استفاده از همان نمادگذاری مشابه C). طول تمامی رشته‌ها به مقداری معقول (چند صد بایت) محدود است. اعداد صحیح مقادیری ۶۴ بیتی و علامت‌دار هستند، اگرچه تجزیه‌کننده مقادیر بالاتر از 2**63 مثبت را نیز می‌پذیرد (و دور می‌زند). .PP علاوه بر این، آرگومان‌های اسکریپت که در انتهای خط فرمان داده شده‌اند را می‌توان درج کرد. از .B $1 ... $ برای درج بدون نقل‌قول، و از .B @1 ... @ برای درج به عنوان رشته متنی استفاده کنید. تعداد آرگومان‌ها از طریق .B $# (به عنوان عدد بدون نقل‌قول) یا از طریق .B @# (به عنوان عدد با نقل‌قول) قابل دسترسی است. این‌ها ممکن است در هر جایی که یک نشانه می‌تواند آغاز شود، از جمله در مرحله پیش‌پردازش، استفاده شوند. ارجاع به شماره آرگومانی فراتر از آنچه در واقع ارائه شده است یک خطا است. .SS "پیش‌پردازش (PREPROCESSING)" یک مرحله پیش‌پردازش شرطی ساده به عنوان بخشی از تجزیه اجرا می‌شود. شکل کلی آن مشابه عملگر سه‌تایی .RB cond " ? " exp1 " : " exp2 است: .SAMPLE .BR %( " CONDITION " %? " TRUE-TOKENS " %) .BR %( " CONDITION " %? " TRUE-TOKENS " %: " FALSE-TOKENS " %) .ESAMPLE شرط (CONDITION) یا عبارتی است که قالب آن توسط اولین کلیدواژه آن تعیین می‌شود، یا مقایسه‌ای از رشته‌های متنی یا مقایسه‌ای از مقادیر عددی ثابت است. همچنین می‌تواند از چندین حالت جایگزین و عطف‌های مختلف از CONDITIONها (به همان معنای جمله قبل) با استفاده از || و && تشکیل شود. با این حال، پرانتزها هنوز پشتیبانی نمی‌شوند، بنابراین به خاطر سپردن این نکته که عطف (&&) بر فصل (||) اولویت دارد، اهمیت دارد. .PP اگر بخش اول شناسه .BR kernel_vr " یا " kernel_v برای اشاره به شماره نسخه هسته باشد، همراه با پسوند کد انتشار ("2.6.13\-1.322FC3smp") یا بدون آن ("2.6.13")، آنگاه بخش دوم یکی از شش عملگر مقایسه عددی استاندارد است: .BR < ", " <= ", " == ", " != ", " > ", و " >= , و بخش سوم یک مقدار رشته‌ای است که حاوی مقدار نسخه-انتشار به سبک RPM است. شرط در صورتی برآورده تلقی می‌شود که نسخه هسته هدف (که به صورت اختیاری توسط گزینه .BR \-r لغو شده است) با رشته نسخه داده‌شده مقایسه شود. این مقایسه توسط تابع glibc به نام .BR strverscmp انجام می‌شود. به عنوان یک حالت خاص، اگر عملگر برای برابری ساده .RB ( == ), یا نابرابری .RB ( != ), باشد و بخش سوم حاوی هرگونه نویسه عمومی مانند .RB ( * " یا " ? " یا " [ ")," باشد، عبارت به عنوان تطبیق عمومی ارزیابی‌شده توسط .BR fnmatch در نظر گرفته می‌شود. .PP اگر از سوی دیگر، بخش اول شناسه .BR arch برای اشاره به معماری پردازنده باشد (همان‌طور که توسط سیستم ساخت هسته ARCH/SUBARCH نامگذاری شده است)، آنگاه بخش دوم یکی از دو عملگر مقایسه رشته‌ای .BR == " یا " != است، و بخش سوم یک رشته متنی برای تطبیق با آن است. این مقایسه یک تطبیق عمومی است. .PP به همین ترتیب، اگر بخش اول شناسه‌ای مانند .BR CONFIG_something برای اشاره به یک گزینه پیکربندی هسته باشد، بخش دوم .BR == " یا " != است و بخش سوم یک رشته متنی برای تطبیق با مقدار آن است (معمولاً "y" یا "m"). گزینه‌های پیکربندی هسته ناموجود یا تنظیم‌نشده با رشته خالی نمایش داده می‌شوند. این مقایسه نیز یک تطبیق عمومی است. .PP اگر بخش اول شناسه .BR systemtap_v باشد، آزمون به نسخه سازگاری systemtap اشاره دارد که ممکن است برای اسکریپت‌های قدیمی با فلگ .BI \-\-compatible لغو شود. عملگر مقایسه همانند .BR kernel_v است و عملوند راست یک رشته نسخه است. همچنین بخش «منسوخ‌شدگی (DEPRECATION)» در ادامه را ببینید. .PP اگر بخش اول شناسه .BR systemtap_privilege باشد، آزمون به سطح دسترسی‌ای اشاره دارد که اسکریپت systemtap با آن کامپایل شده است. در اینجا بخش دوم .BR == " یا " != است و بخش سوم یک رشته متنی است که یکی از مقادیر "stapusr"، "stapsys" یا "stapdev" خواهد بود. .PP اگر بخش اول شناسه .BR guru_mode باشد، آزمون بررسی می‌کند که آیا اسکریپت systemtap با guru_mode کامپایل شده است یا خیر. در اینجا بخش دوم .BR == " یا " != است و بخش سوم یک عدد است، یا 1 یا 0. .PP اگر بخش اول شناسه .BR runtime باشد، آزمون به حالت زمان اجرای systemtap اشاره دارد. برای اطلاعات بیشتر درباره زمان‌های اجرا، بخش .BR "زمان‌های اجرای جایگزین (ALTERNATE RUNTIMES)" در ادامه را ببینید. بخش دوم یکی از دو عملگر مقایسه رشته‌ای .BR == " یا " != است و بخش سوم یک رشته متنی برای تطبیق با آن است. این مقایسه یک تطبیق عمومی است. .PP در غیر این صورت، انتظار می‌رود که CONDITION مقایسه‌ای بین دو رشته متنی یا دو مقدار عددی باشد. در این حالت، آرگومان‌ها تنها متغیرهای قابل استفاده هستند. .PP نشانه‌های TRUE-TOKENS و FALSE-TOKENS صفر یا چند نشانه عمومی تجزیه‌کننده هستند (احتمالاً شامل پیش‌پردازنده‌های شرطی تو در تو)، و بسته به درستی یا نادرستی شرط به جریان ورودی ارسال می‌شوند. برای مثال، کد زیر موجب خطای تجزیه می‌شود مگر اینکه نسخه هسته هدف جدیدتر از 2.6.5 باشد: .SAMPLE %( kernel_v <= "2.6.5" %? **ERROR** %) # توالی نامعتبر نشانه .ESAMPLE کد زیر ممکن است با تغییرات فرضی نسخه هسته سازگار شود: .SAMPLE probe kernel.function ( %( kernel_v <= "2.6.12" %? "__mm_do_fault" %: %( kernel_vr == "2.6.13*smp" %? "do_page_fault" %: UNSUPPORTED %) %) ) { /* ... */ } %( arch == "ia64" %? probe syscall.vliw = kernel.function("vliw_widget") {} %) .ESAMPLE .SS "ماکروهای پیش‌پردازنده (PREPROCESSOR MACROS)" پیش‌پردازنده همچنین از یک امکان ماکروی ساده پشتیبانی می‌کند که به عنوان یک گذر مجزا پیش از پیش‌پردازش شرطی اجرا می‌شود. .PP ماکروها با استفاده از ساختار زیر تعریف می‌شوند: .SAMPLE @define NAME %( BODY %) @define NAME(PARAM_1, PARAM_2, ...) %( BODY %) .ESAMPLE ماکروها و پارامترهای داخل بدنه ماکرو هر دو با قرار دادن نماد @ در ابتدای نام ماکرو فراخوانی می‌شوند: .SAMPLE @define foo %( x %) @define add(a,b) %( ((@a)+(@b)) %) @foo = @add(2,2) .ESAMPLE .PP بسط ماکروها در حال حاضر در یک گذر مجزا قبل از کامپایل شرطی انجام می‌شود. بنابراین، نشانه‌های TRUE و FALSE در عبارات شرطی صرف‌نظر از نحوه ارزیابی شرط، بسط داده می‌شوند. این گاهی اوقات می‌تواند منجر به بروز خطا شود: .SAMPLE // مورد زیر منجر به تداخل می‌شود: %( CONFIG_UPROBE == "y" %? @define foo %( process.syscall %) %: @define foo %( **ERROR** %) %) // مورد زیر مطابق انتظار به درستی کار می‌کند: @define foo %( %( CONFIG_UPROBE == "y" %? process.syscall %: **ERROR** %) %) .ESAMPLE مثال اول نادرست است زیرا هر دو @define در گذری پیش از ارزیابی شرط ارزیابی می‌شوند. به طور معمول، تعریف یک ماکرو محلی برای فایلی است که در آن رخ می‌دهد. بنابراین، تعریف یک ماکرو در یک تپ‌ست آن را در دسترس کاربر آن تپ‌ست قرار نمی‌دهد. ماکروهای کتابخانه‌ای در دسترس عمومی را می‌توان با گنجاندن فایل‌های ‎.stpm در مسیر جستجوی تپ‌ست تعریف کرد. این فایل‌ها فقط می‌توانند حاوی ساختارهای @define باشند که در سراسر تمام تپ‌ست‌ها و اسکریپت‌های کاربر قابل مشاهده خواهند بود. به صورت اختیاری، درون فایل‌های ‎.stpm، یک تعریف ماکروی عمومی می‌تواند توسط یک پیش‌پردازنده شرطی احاطه شود، همان‌طور که در بالا شرح داده شد. .SS "ثابت‌ها (CONSTANTS)" تپ‌ست‌ها یا اسکریپت‌های کاربر در حالت guru می‌توانند با استفاده از عملگر داخلی @const() به نشانه‌های ثابت فایل سرآیند، که معمولاً ماکروها هستند، دسترسی پیدا کنند. گنجاندن فایل سرآیند مربوطه از طریق کتابخانه تپ‌ست یا با استفاده از یک ساختار C جاسازی‌شده سطح بالا در حالت guru امکان‌پذیر است. این منجر به تنظیم توضیحات پراگمای مناسب کد C جاسازی‌شده می‌شود. .SAMPLE @const("STP_SKIP_BADVARS") .ESAMPLE .PP ثابت‌های شمارشی برنامه‌های اشکال‌زدایی‌شده را می‌توان با استفاده از عملگر داخلی @enum() در دسترس قرار داد. این عملگر نام ثابت شمارشی را در اطلاعات اشکال‌زدایی DWARF جستجو کرده و آن را با مقدار صحیح آن جایگزین می‌کند. .SAMPLE @enum("MY_ENUM_CONSTANT") .ESAMPLE .SS "متغیرها (VARIABLES)" شناسه‌های متغیرها و توابع یک دنباله حرفی-عددی هستند و ممکن است شامل نویسه‌های \fB_\fR و \fB$\fR باشند. آن‌ها نمی‌توانند با یک رقم ساده شروع شوند، همانند C. هر متغیر به صورت پیش‌فرض محلی برای بلوک دستورات کاوشگر یا تابعی است که در آن ذکر شده است، و بنابراین دامنه و طول عمر آن به یک فراخوانی کاوشگر یا تابع خاص محدود است. .PP متغیرهای اسکالر به طور ضمنی دارای نوع رشته‌ای یا عدد صحیح هستند. آرایه‌های انجمنی نیز دارای مقدار رشته‌ای یا عددی بوده و یک چندتایی از رشته‌ها و/یا اعداد صحیح به عنوان کلید آن‌ها عمل می‌کند. در اینجا چند عبارت پایه آورده شده است: .SAMPLE var1 = 5 var2 = "bar" array1 [pid()] = "name" # کلید عددی تکی array2 ["foo",4,i++] += 5 # برداری از کلیدهای رشته/عدد/عدد if (["hello",5,4] in array2) println ("yes") # آزمون عضویت .ESAMPLE .PP مترجم استنتاج نوع را روی تمام شناسه‌ها، از جمله شاخص‌های آرایه و پارامترهای توابع انجام می‌دهد. استفاده ناسازگار مرتبط با نوع از شناسه‌ها نشان‌دهنده خطا است. .PP متغیرها ممکن است سراسری اعلان شوند، به طوری که بین تمام کاوشگرها و توابع به اشتراک گذاشته شوند و تا پایان کل نشست systemtap زنده بمانند. یک فضای نام برای تمام متغیرهای سراسری وجود دارد، صرف‌نظر از اینکه در کدام فایل اسکریپت قرار داشته باشند. دسترسی همزمان به متغیرهای سراسری به طور خودکار با قفل‌ها محافظت می‌شود؛ برای جزئیات بیشتر بخش .B "ایمنی و امنیت (SAFETY AND SECURITY)" را ببینید. یک اعلان سراسری را می‌توان در بیرونی‌ترین سطح در هر جایی نوشت، نه در داخل یک بلوک کد. متغیرهای سراسری که نوشته شده اما هرگز خوانده نشده‌اند، در هنگام خاتمه نشست به طور خودکار نمایش داده می‌شوند. مترجم برای هر یک از آن‌ها نوع مقدار آن، و در صورت استفاده به عنوان آرایه، انواع کلیدهای آن را استنتاج می‌کند. به صورت اختیاری، متغیرهای سراسری اسکالر ممکن است با یک مقدار رشته‌ای یا عددی مقداردهی اولیه شوند. اعلان زیر متغیرها را سراسری تعیین می‌کند: .SAMPLE .BR global " var1" , " var2" , " var3=4" .ESAMPLE .PP متغیرهای سراسری را می‌توان به عنوان گزینه‌های ماژول نیز تنظیم کرد. این کار را می‌توان با استفاده از گزینه \-G انجام داد، یا ماژول ابتدا باید با استفاده از stap \-p4 کامپایل شود. سپس می‌توان متغیرهای سراسری را در خط فرمان هنگام فراخوانی staprun روی ماژول تولیدشده توسط stap \-p4 تنظیم کرد. برای اطلاعات بیشتر به .IR staprun (8) مراجعه کنید. .PP دامنه یک متغیر سراسری را می‌توان با استفاده از کلیدواژه private به یک تپ‌ست یا فایل اسکریپت کاربر محدود کرد. کلیدواژه global هنگام تعریف یک متغیر سراسری خصوصی اختیاری است. اعلان زیر var1 و var2 را به عنوان سراسری‌های خصوصی تعیین می‌کند: .SAMPLE .BR private " global" " var1=2" .BR private " var2" .ESAMPLE .PP اندازه آرایه‌ها توسط متغیر MAXMAPENTRIES محدود می‌شود -- برای جزئیات به بخش .B "ایمنی و امنیت (SAFETY AND SECURITY)" مراجعه کنید. به صورت اختیاری، آرایه‌های سراسری ممکن است با حداکثر اندازه در قلاب‌ها اعلان شوند، که MAXMAPENTRIES را فقط برای آن آرایه لغو می‌کند. توجه داشته باشید که این نشان‌دهنده نوع کلیدهای آرایه نیست، بلکه فقط اندازه را مشخص می‌کند. .SAMPLE .BR global " tiny_array[10]" , " normal_array" , " big_array[50000]" .ESAMPLE .PP آرایه‌ها را می‌توان با استفاده از پسوند '%' برای چرخش پیکربندی کرد. این امر باعث می‌شود در صورتی که عناصر بیشتری نسبت به گنجایش آرایه درج شوند، عناصر قدیمی‌تر بازنویسی شوند. این هم برای آرایه‌های انجمنی و هم برای آرایه‌های با نوع آماری کار می‌کند. .SAMPLE .BR global " wrapped_array1%[10]", " wrapped_array2%" .ESAMPLE .PP بسیاری از انواع نقاط کاوش متغیرهای زمینه را فراهم می‌کنند، که مقادیر زمان اجرا هستند و به طور ایمن از هسته یا برنامه فضای کاربری تحت کاوش استخراج می‌شوند. این‌ها با نویسه \fB$\fR پیشوندگذاری می‌شوند. بخش CONTEXT VARIABLES در .IR stapprobes (3stap) آنچه برای هر نوع نقطه کاوش در دسترس است را فهرست می‌کند. این متغیرهای زمینه پس از ذخیره شدن در متغیرهای عادی اسکریپت، به مقادیر اسکالر رشته‌ای یا عددی عادی تبدیل می‌شوند. برای نحوه تبدیل مجدد آن‌ها به اشاره‌گرهای دارای نوع برای پردازش بیشتر به عنوان متغیرهای زمینه، بخش «تبدیل نوع (TYPECASTING)» را در ادامه ببینید. برای کمک به این امر خودکارسازی‌هایی وجود دارد! .SS "دستورات (STATEMENTS)" دستورات جریان کنترل رویه‌ای را امکان‌پذیر می‌سازند. آن‌ها ممکن است در توابع و گرداننده‌های کاوشگر رخ دهند. تعداد کل دستورات اجراشده در پاسخ به هر رویداد کاوش تکی به عددی محدود می‌شود که توسط ماکروی MAXACTION در کد C ترجمه‌شده تعریف شده است و در حدود ۱۰۰۰ دستور است. .TP EXP عبارت با مقدار رشته‌ای یا عددی را اجرا کرده و مقدار را دور می‌ریزد. .TP .BR { " STMT1 STMT2 ... " } هر دستور را به ترتیب در این بلوک اجرا می‌کند. توجه داشته باشید که جداکننده‌ها یا پایان‌دهنده‌ها معمولاً بین دستورات ضروری نیستند. .TP .BR ; دستور خالی، کاری انجام نمی‌دهد. این به عنوان یک جداکننده اختیاری بین دستورات برای بهبود تشخیص خطاهای نحوی و مدیریت برخی ابهامات گرامری مفید است. .TP .BR if " (EXP) STMT1 [ " else " STMT2 ]" عبارت عددی EXP را با صفر مقایسه می‌کند. اولین STMT (غیر صفر) یا دومین STMT (صفر) را اجرا می‌کند. .TP .BR while " (EXP) STMT" تا زمانی که مقدار عددی EXP غیر صفر ارزیابی شود، STMT را اجرا می‌کند. .TP .BR for " (EXP1; EXP2; EXP3) STMT" عبارت EXP1 را به عنوان مقداردهی اولیه اجرا می‌کند. تا زمانی که EXP2 غیر صفر است، STMT و سپس عبارت تکرار EXP3 را اجرا می‌کند. .TP .BR foreach " (VAR " in " ARRAY [ "limit " EXP ]) STMT" روی هر عنصر از آرایه سراسری نامگذاری‌شده حلقه می‌زند و کلید فعلی را به VAR تخصیص می‌دهد. آرایه ممکن است در طول دستور اصلاح نشود. با افزودن یک عملگر تکی .BR + " یا " \- بعد از شناسه VAR یا ARRAY، تکرار به ترتیب مرتب‌شده، بر اساس شاخص یا مقدار صعودی یا نزولی پیش می‌رود. اگر آرایه حاوی مقادیر تجمیعی آماری باشد، افزودن عملگر .BR @operator مورد نظر بین شناسه ARRAY و .BR + " یا " \- تابع تجمیع مرتب‌سازی را مشخص می‌کند. برای موارد موجود، بخش «آمار (STATISTICS)» را در ادامه ببینید. پیش‌فرض .BR @count است. استفاده از کلیدواژه اختیاری .BR limit تعداد تکرارهای حلقه را به EXP بار محدود می‌کند. EXP یک بار در ابتدای حلقه ارزیابی می‌شود. .TP .BR foreach " ([VAR1, VAR2, ...] " in " ARRAY [ "limit " EXP ]) STMT" همانند بالا، در زمانی استفاده می‌شود که آرایه با یک چندتایی از کلیدها شاخص‌گذاری شده باشد. پسوند مرتب‌سازی ممکن است حداکثر روی یک شناسه VAR یا ARRAY استفاده شود. .TP .BR foreach " ([VAR1, VAR2, ...] " in " ARRAY [INDEX1, INDEX2, ...] [ "limit " EXP ]) STMT" همانند بالا، که در آن تکرارها به عناصری از آرایه محدود می‌شوند که کلیدهای آن‌ها با مقادیر شاخص مشخص‌شده مطابقت داشته باشد. نماد * می‌تواند برای تعیین یک شاخص استفاده شود و به عنوان نویسه عمومی رفتار خواهد کرد. .TP .BR foreach " (VAR0 = VAR " in " ARRAY [ "limit " EXP ]) STMT" این نوع foreach مقدار فعلی را در هر تکرار در VAR0 ذخیره می‌کند، بنابراین مشابه ARRAY[VAR] است. این همچنین با چندتایی از کلیدها کار می‌کند. پسوندهای مرتب‌سازی روی VAR0 همان تأثیر روی ARRAY را دارند. .TP .BR foreach " (VAR0 = VAR " in " ARRAY [INDEX1, INDEX2, ...] [ "limit " EXP ]) STMT" همانند بالا، که در آن تکرارها به عناصری در آرایه محدود می‌شوند که کلیدها با مقادیر شاخص مشخص‌شده تطابق داشته باشند. نماد * می‌تواند برای تعیین یک شاخص استفاده شود و به عنوان نویسه عمومی رفتار خواهد کرد. .TP .BR break ", " continue خروج یا تکرار درونی‌ترین حلقه تو در تو .RB ( while " یا " for " یا " foreach ). .TP .BR return " EXP" بازگرداندن مقدار EXP از تابع محصورکننده. اگر مقدار تابع در جایی دریافت نشود، به دستور return نیازی نیست و تابع دارای نوع ویژه «unknown» بدون مقدار بازگشتی خواهد بود. .TP .BR next بازگشت فوری از گرداننده کاوشگر محصورکننده. این به ویژه در نام‌های مستعار کاوشگر که گزاره‌های فیلتر رویداد را اعمال می‌کنند مفید است. هنگام استفاده در توابع، اجرا بلافاصله به تابع اورلودشده بعدی منتقل می‌شود. .TP .BR try " { STMT1 } " catch " { STMT2 }" اجرای دستورات در بلوک اول. هنگام بروز هرگونه خطای زمان اجرا، STMT1 را متوقف کرده و شروع به اجرای STMT2 می‌کند. هرگونه خطا در STMT2 به بلوک‌های بیرونی try/catch (در صورت وجود) انتشار می‌یابد. .TP .BR try " { STMT1 } " catch "(VAR) { STMT2 }" همانند بالا، به علاوه تخصیص پیام خطا به متغیر اسکالر رشته‌ای VAR. .TP .BR delete " ARRAY[INDEX1, INDEX2, ...]" حذف عنصر مشخص‌شده توسط چندتایی شاخص از ARRAY. اگر چندتایی شاخص شامل یک * به‌جای یک شاخص باشد، * به عنوان نویسه عمومی در نظر گرفته می‌شود و تمام عناصری که کلیدهایشان با چندتایی شاخص مطابقت داشته باشد از ARRAY حذف خواهند شد. مقدار دیگر در دسترس نخواهد بود و تکرارهای بعدی عنصر را گزارش نخواهند کرد. حذف عنصری که وجود ندارد خطا محسوب نمی‌شود. .TP .BR delete " ARRAY" حذف تمام عناصر از ARRAY. .TP .BR delete " SCALAR" مقدار SCALAR را حذف می‌کند. اعداد صحیح و رشته‌ها به ترتیب به 0 و "" پاک می‌شوند، در حالی که مقادیر آماری به حالت خالی اولیه بازنشانی می‌شوند. .SS "عبارات (EXPRESSIONS)" سیستم‌تپ از تعدادی عملگر پشتیبانی می‌کند که دارای نحو عمومی، معنایی و اولویت مشابه با C و awk هستند. محاسبات بر اساس قواعد معمولی C برای اعداد صحیح علامت‌دار انجام می‌شود. تقسیم بر صفر یا سرریز تشخیص داده شده و منجر به خطا می‌شود. .TP عملگرهای عددی دودویی .B * / % + \- >> << & ^ | && || .TP عملگرهای رشته‌ای دودویی .B . (الحاق رشته) .TP عملگرهای انتساب عددی .B = *= /= %= += \-= >>= <<= &= ^= |= .TP عملگرهای انتساب رشته‌ای .B = .= .TP عملگرهای عددی یکانی .B + \- ! ~ ++ \-\- .TP عملگرهای مقایسه عددی، رشته‌ای یا تطبیق عبارات باقاعده دودویی .B < > <= >= == != =~ !~ .TP عملگر سه‌تایی .RB cond " ? " exp1 " : " exp2 .TP عملگر گروه‌بندی .BR ( " exp " ) .TP فراخوانی تابع .RB "fn " ( "[ arg1, arg2, ... ]" ) .TP بررسی عضویت در آرایه .RB exp " in " array .br .BR "[" exp1 ", " exp2 ", ... ] in " array .br .BR "[" * ", " * ", ... ] in " array .SS "تطبیق عبارات باقاعده (REGULAR EXPRESSION MATCHING)" زبان اسکریپت‌نویسی از تطبیق عبارات باقاعده پشتیبانی می‌کند. نحو پایه به شکل زیر است: .SAMPLE .BR exp " =~ " regex .BR exp " !~ " regex .ESAMPLE (عملوند اول باید عبارتی باشد که به یک رشته ارزیابی می‌شود؛ عملوند دوم باید یک رشته متنی حاوی یک عبارت باقاعده از نظر نحوی معتبر باشد.) .PP نحو عبارت باقاعده از ویژگی‌های عبارات باقاعده توسعه‌یافته POSIX همان‌طور که در .IR grep (1) مستند شده است، به جز قابلیت استفاده مجدد از زیرعبارت ("\\1") پشتیبانی می‌کند. .PP پس از یک تطبیق موفق، محتوای رشته تطبیق‌یافته و زیرعبارت‌ها را می‌توان با استفاده از توابع تپ‌ست matched() و ngroups() به شکل زیر استخراج کرد: .SAMPLE if ("an example string" =~ "str(ing)") { matched(0) // -> مقدار "string"، زیررشته تطبیق‌یافته را برمی‌گرداند matched(1) // -> مقدار "ing"، اولین زیرعبارت تطبیق‌یافته را برمی‌گرداند ngroups() // -> مقدار 2، تعداد گروه‌های تطبیق‌یافته را برمی‌گرداند } .ESAMPLE .PP .SS "کاوشگرها (PROBES)" ساختار اصلی در زبان اسکریپت‌نویسی، کاوشگرها را مشخص می‌کند. کاوشگرها رویدادهای انتزاعی را با یک بلوک دستورات («گرداننده کاوشگر» یا probe handler) پیوند می‌دهند که در هنگام رخ دادن هر یک از آن رویدادها اجرا می‌شود. نحو عمومی به صورت زیر است: .SAMPLE .BR probe " PROBEPOINT [" , " PROBEPOINT] " { " [STMT ...] " } .BR probe " PROBEPOINT [" , " PROBEPOINT] " "if (" CONDITION ") { " "[STMT ...]" " }" .ESAMPLE .PP رویدادها با نحوی خاص به نام «نقاط کاوش» (probe points) مشخص می‌شوند. انواع مختلفی از نقاط کاوش توسط مترجم تعریف شده‌اند و اسکریپت‌های تپ‌ست می‌توانند موارد بیشتری را با استفاده از نام‌های مستعار تعریف کنند. نقاط کاوش ممکن است دارای نویسه‌های عمومی باشند، گروه‌بندی شوند، در دنباله‌های اولویت‌دار فهرست شوند، یا به عنوان اختیاری اعلان شوند. جزئیات بیشتر درباره نحو و معناشناسی نقاط کاوش در صفحه راهنمای .IR stapprobes (3stap) فهرست شده است. .PP گرداننده کاوشگر متناسب با زمینه (context) هر رویداد تفسیر می‌شود. برای رویدادهای مرتبط با کد هسته، این زمینه ممکن است شامل .I متغیرهایی باشد که در .I کد منبع در آن نقطه تعریف شده‌اند. این «متغیرهای زمینه» به عنوان متغیرهایی که نام آن‌ها با "$" پیشوندگذاری شده است به اسکریپت ارائه می‌شوند. این متغیرها تنها در صورتی قابل دسترسی هستند که کامپایلر هسته علیرغم بهینه‌سازی‌ها آن‌ها را حفظ کرده باشد. این همان محدودیتی است که کاربر یک دیباگر هنگام کار با کد بهینه‌شده با آن مواجه می‌شود. علاوه بر این، اشیاء باید در لحظه اجرای گرداننده کاوشگر systemtap در حافظه صفحه‌بندی‌شده (paged-in) وجود داشته باشند، زیرا systemtap نباید هیچ‌گونه صفحه‌بندی اضافی ایجاد کند (آن را سرکوب می‌کند). برخی از انواع کاوشگرها دارای زمینه بسیار کمی هستند. صفحات راهنمای .IR stapprobes (3stap) را برای دیدن انواع متغیرهای زمینه موجود در هر نوع نقطه کاوش ببینید. از نسخه ۴.۳ سیستم‌تپ، توابعی که از درون گرداننده‌های برخی از انواع نقاط کاوش فراخوانی می‌شوند نیز ممکن است به متغیرهای زمینه ارجاع دهند. با این موارد به گونه‌ای رفتار می‌شود که گویی کلونی از آن تابع در گرداننده کاوشگر فراخواننده به صورت درون‌خطی قرار گرفته و متغیرهای $ در زمینه آن ارزیابی شده‌اند. .PP کاوشگرها ممکن است با یک .IR "شرط مسلح‌سازی (arming condition)" تزیین شوند، که شامل یک عبارت بولی ساده روی متغیرهای سراسری فقط‌خواندنی اسکریپت است. در حالی که کاوشگر غیرمسلح (غیرفعال، ارزیابی شرط به نادرست) است، برخی از انواع کاوشگرها بار پردازشی زمان اجرای خود را کاهش داده یا حذف می‌کنند. هنگامی که یک شرط مسلح‌سازی به درست ارزیابی شود، کاوشگرها .I به زودی مجدداً مسلح می‌شوند، و با فعال شدن رویدادها، گرداننده‌های کاوشگر آن‌ها شروع به فراخوانی شدن می‌کنند. (برخی رویدادها ممکن است در طول بازه مسلح‌سازی از دست بروند. اگر این امر غیرقابل قبول است، از شرایط مسلح‌سازی برای آن کاوشگرها استفاده نکنید.) مثالی از نحو: .SAMPLE probe timer.us(TIMER) if (enabled) { ... } .ESAMPLE .PP نقاط کاوش جدید را می‌توان با استفاده از «نام‌های مستعار» (aliases) تعریف کرد. نام‌های مستعار نقاط کاوش شبیه به تعاریف کاوشگر هستند، اما به‌جای فعال‌سازی کاوشگر در نقطه داده‌شده، صرفاً نام نقطه کاوش جدیدی را به عنوان نام مستعار برای یک نقطه موجود تعریف می‌کنند. دو نوع نام مستعار وجود دارد، یعنی سبک پیش‌درآمد (prologue) و سبک پس‌درآمد (epilogue) که به ترتیب با "=" و "+=" مشخص می‌شوند. .PP برای نام مستعار سبک پیش‌درآمد، بلوک دستوراتی که بعد از تعریف نام مستعار می‌آید، به طور ضمنی به عنوان یک پیش‌درآمد به هر کاوشگری که به این نام مستعار ارجاع می‌دهد اضافه می‌شود. در حالی که برای نام مستعار سبک پس‌درآمد، بلوک دستوراتی که بعد از تعریف نام مستعار می‌آید، به طور ضمنی به عنوان یک پس‌درآمد به هر کاوشگری که به این نام مستعار ارجاع می‌دهد اضافه می‌شود. برای مثال: .SAMPLE probe syscall.read = kernel.function("sys_read") { fildes = $fd if (execname() == "init") next # رد کردن ادامه کاوشگر } .ESAMPLE یک نقطه کاوش جدید به نام .nh .IR syscall.read .hy تعریف می‌کند، که به .nh .IR kernel.function("sys_read") .hy بسط می‌یابد، همراه با دستور داده‌شده به عنوان یک پیش‌درآمد، که برای از پیش تعریف کردن برخی متغیرها برای کاربر نام مستعار و/یا برای رد کردن کامل پردازش کاوشگر بر اساس برخی شرایط مفید است. و .SAMPLE probe syscall.read += kernel.function("sys_read") { if (tracethis) println ($fd) } .ESAMPLE یک نقطه کاوش جدید همراه با دستور داده‌شده به عنوان پس‌درآمد تعریف می‌کند، که برای انجام اقداماتی بر اساس متغیرهای تنظیم‌شده یا باقی‌مانده توسط کاربر نام مستعار مفید است. لطفاً توجه داشته باشید که در هر حالت، با دستورات موجود در بلوک گرداننده نام مستعار به صورت عادی رفتار می‌شود، به‌طوری که متغیرهای اختصاص‌یافته در آنجا صرفاً مقداردهی اولیه را تشکیل می‌دهند، نه یک جایگزینی ماکرو. نام‌های مستعار را می‌توان به گونه‌ای نیز تعریف کرد که شامل هر دو بخش پیش‌درآمد و پس‌درآمد باشند. .SAMPLE probe syscall.read = kernel.function("sys_read") { fildes = $fd if (execname() == "init") next },{ if (tracethis) println ($fd) } .ESAMPLE یک نام مستعار دقیقاً مانند یک نوع کاوشگر توکار استفاده می‌شود. .SAMPLE probe syscall.read { printf("reading fd=%d\\n", fildes) if (fildes > 10) tracethis = 1 } .ESAMPLE کاوشگرهای دارای نام مستعار می‌توانند از گزاره @probewrite استفاده کنند. این بررسی برای تشخیص این است که آیا در بدنه گرداننده کاوشگر در یک متغیر اسکریپت یا متغیر هدف مقداری نوشته شده است یا خیر. .TP @probewrite(var) در صورتی و تنها در صورتی به 1 بسط می‌یابد که در بدنه گرداننده کاوشگر روی var نوشته شده باشد، در غیر این صورت به 0 بسط می‌یابد. .ETP .PP در مثال زیر، @probewrite(var) به 1 بسط می‌یابد زیرا در بدنه گرداننده کاوشگر روی var نوشته شده است و در نتیجه، دستور شرطی اجرا خواهد شد. .SAMPLE probe foo = begin { var = 0 }, { if (@probewrite(var)) println(var) } probe foo { var = 1 } .ESAMPLE .SS "توابع (FUNCTIONS)" اسکریپت‌های systemtap می‌توانند زیرروال‌هایی را برای تفکیک کارهای مشترک تعریف کنند. توابع هر تعداد آرگومان اسکالر (عدد صحیح یا رشته) را می‌پذیرند و باید یک اسکالر منفرد (عدد صحیح یا رشته) را برگردانند. یک نمونه اعلان تابع به این صورت است: .SAMPLE function thisfn (arg1, arg2) { return arg1 + arg2 } .ESAMPLE به عدم وجود کلی اعلان نوع توجه داشته باشید که در عوض توسط مترجم استنتاج می‌شود. با این حال، در صورت تمایل، یک تعریف تابع می‌تواند شامل اعلان‌های نوع صریح برای مقدار بازگشتی و/یا آرگومان‌های آن باشد. این به ویژه برای توابع C جاسازی‌شده مفید است. در مثال زیر، موتور استنتاج نوع تنها نیاز دارد نوع arg2 (یک رشته) را استنتاج کند: .SAMPLE function thatfn:string (arg1:long, arg2) { return sprint(arg1) . arg2 } .ESAMPLE توابع ممکن است توابع دیگر یا خود را به صورت بازگشتی، تا یک محدودیت تودرتویی ثابت فراخوانی کنند. این محدودیت توسط ماکروی MAXNESTING در کد C ترجمه‌شده تعریف شده و در حدود ۱۰ است. توابع را می‌توان با استفاده از کلیدواژه private خصوصی علامت‌گذاری کرد تا دامنه آن‌ها به تپ‌ست یا فایل اسکریپت کاربری که در آن تعریف شده‌اند محدود شود. یک نمونه تعریف از یک تابع خصوصی در ادامه آمده است: .SAMPLE private function three:long () { return 3 } .ESAMPLE توابعی که بدون رسیدن به دستور return صریح خاتمه می‌یابند، یک مقدار ضمنی 0 یا "" را برمی‌گردانند که توسط استنتاج نوع تعیین می‌شود. توابع را می‌توان در زمان اجرا و زمان کامپایل اورلود (overload) کرد. اورلودینگ زمان اجرا امکان می‌دهد که تابع اجراشونده در حین اجرای ماژول بر اساس شرایط زمان اجرا انتخاب شود و این با استفاده از دستور «next» در توابع اسکریپت و ماکروی STAP_NEXT برای توابع C جاسازی‌شده حاصل می‌شود. برای مثال: .SAMPLE function f() { if (condition) next; print("first function") } function f() %{ STAP_NEXT; print("second function") %} function f() { print("third function") } .ESAMPLE در طول فراخوانی تابع f()، در صورتی که condition به درست ارزیابی شود، اجرا به تابع سوم منتقل شده و عبارت "third function" را چاپ می‌کند. توجه داشته باشید که تابع دوم بدون قید و شرط به تابع بعدی منتقل می‌شود (unconditionally nexted). اورلودینگ پارامتر امکان می‌دهد تابع اجراشونده در زمان کامپایل بر اساس تعداد آرگومان‌های ارائه‌شده به فراخوانی تابع انتخاب شود. برای مثال: .SAMPLE function g() { print("first function") } function g(x) { print("second function") } g() -> "first function" g(1) -> "second function" .ESAMPLE توجه داشته باشید که اورلودینگ زمان اجرا در مثال بالا رخ نمی‌دهد، زیرا دقیقاً یک تابع برای فراخوانی تابع حل خواهد شد. استفاده از دستور next در داخل یک تابع در حالی که هیچ اورلود دیگری باقی نمانده باشد، یک استثنای زمان اجرا ایجاد می‌کند. اورلودینگ زمان اجرا تنها در صورتی رخ می‌دهد که توابع دارای تعداد پارامترهای یکسان باشند؛ توابع با نام یکسان اما تعداد پارامترهای متفاوت کاملاً بی‌ارتباط هستند. ترتیب اجرا با یک مقدار اولویت که ممکن است مشخص شود تعیین می‌گردد. اگر هیچ اولویت صریحی مشخص نشده باشد، به توابع اسکریپت کاربر اولویت بالاتری نسبت به توابع کتابخانه‌ای داده می‌شود. به توابع اسکریپت کاربر و توابع کتابخانه‌ای به ترتیب مقدار اولویت پیش‌فرض 0 و 1 اختصاص می‌یابد. توابع با اولویت یکسان به ترتیب اعلان اجرا می‌شوند. برای مثال: .SAMPLE function f():3 { if (condition) next; print("first function") } function f():1 { if (condition) next; print("second function") } function f():2 { print("third function") } .ESAMPLE از آنجا که تابع دوم بالاترین اولویت را دارد، ابتدا اجرا می‌شود. تابع اول هرگز اجرا نمی‌شود زیرا هیچ دستور "next" در تابع سوم برای انتقال اجرا وجود ندارد. .SS "چاپ (PRINTING)" مجموعه‌ای از نام‌های توابع وجود دارند که به طور ویژه توسط مترجم مورد پردازش قرار می‌گیرند. آن‌ها مقادیر را برای چاپ در جریان خروجی استاندارد systemtap به روشی راحت‌تر قالب‌بندی می‌کنند (توجه داشته باشید که داده‌های تولیدشده در ماژول هسته باید به فضای کاربری منتقل شوند تا چاپ شوند). گونه‌های .IR sprint* به‌جای چاپ رشته قالب‌بندی‌شده، آن را برمی‌گردانند. .TP .BR print ", " sprint چاپ یک یا چند مقدار از هر نوع، که مستقیماً به هم متصل شده‌اند. .TP .BR println ", " sprintln چاپ مقادیر مانند .IR print " و " sprint ، اما همراه با افزودن یک خط جدید (newline). .TP .BR printd ", " sprintd دریافت یک جداکننده رشته‌ای و دو یا چند مقدار از هر نوع، و چاپ مقادیر در حالی که جداکننده بین آن‌ها قرار گرفته است. جداکننده باید یک ثابت رشته‌ای متنی باشد. .TP .BR printdln ", " sprintdln چاپ مقادیر با جداکننده مانند .IR printd " و " sprintd ، اما همراه با افزودن یک خط جدید. .TP .BR printf ", " sprintf دریافت یک رشته قالب‌بندی و تعدادی مقدار از انواع متناظر، و چاپ همه آن‌ها. قالب باید یک ثابت رشته‌ای متنی باشد. .PP دستورالعمل‌های قالب‌بندی .IR printf مشابه دستورالعمل‌های C هستند، با این تفاوت که به طور کامل توسط مترجم بررسی نوع می‌شوند: .RS .TP %b نوشتن یک بلوک باینری از مقدار داده‌شده، به‌جای متن ASCII. مشخص‌کننده عرض، تعداد بایت‌ها را برای نوشتن تعیین می‌کند؛ مشخص‌کننده‌های معتبر %b %1b %2b %4b %8b هستند. پیش‌فرض (%b) برابر با ۸ بایت است. .TP %c نویسه (Character). .TP %d,%i عدد صحیح ده‌دهی علامت‌دار. .TP %m خواندن ایمن حافظه هسته (بدون #) یا حافظه کاربر (با #) در آدرس داده‌شده، و خروجی دادن محتوای آن. مشخص‌کننده دقت اختیاری (نه عرض فیلد) تعداد بایت‌ها را برای خواندن تعیین می‌کند - پیش‌فرض ۱ بایت است. %10.4m تعداد ۴ بایت از حافظه را در یک فیلد با عرض ۱۰ نویسه چاپ می‌کند. توجه داشته باشید که در برخی معماری‌ها حافظه کاربر همچنان می‌تواند بدون # خوانده شود. .TP %M همانند %m، اما خروجی را در مبنای شانزده تولید می‌کند. حداقل اندازه خروجی دو برابر مشخص‌کننده دقت اختیاری است - پیش‌فرض ۱ بایت (۲ نویسه هگز) است. %10.4M تعداد ۴ بایت از حافظه را به عنوان ۸ نویسه هگزادسیمال در فیلدی با عرض ۱۰ نویسه چاپ می‌کند. %.*M یک تخلیه هگزادسیمال از تعداد مشخصی بایت از یک بافر داده‌شده را ارائه می‌دهد. .TP %o عدد در مبنای هشت بدون علامت. .TP %p آدرس اشاره‌گر بدون علامت. .TP %s رشته. .TP %u عدد ده‌دهی بدون علامت. .TP %x مقدار هگزادسیمال بدون علامت، با حروف کوچک. .TP %X مقدار هگزادسیمال بدون علامت، با حروف بزرگ. .TP %% چاپ یک علامت %. .RE .PP فلگ .IR # اشکال جایگزین را انتخاب می‌کند. برای مبنای هشت، یک 0 پیشوند می‌زند. برای هگز، بسته به بزرگی یا کوچکی حروف، 0x یا 0X پیشوند می‌زند. برای نویسه‌ها، مقادیر غیرقابل چاپ را با کدهای گریز مشابه C یا هشت‌هشتی خام گریز می‌دهد. در مورد %#m/%#M، این به طور ایمن به حافظه فضای کاربری دسترسی پیدا می‌کند تا حافظه فضای هسته. .PP مثال‌ها: .SAMPLE a = "alice", b = "bob", p = 0x1234abcd, i = 123, j = \-1, id[a] = 1234, id[b] = 4567 print("hello") Prints: hello println(b) Prints: bob\\n println(a . " is " . sprint(16)) Prints: alice is 16 foreach (name in id) printdln("|", strlen(name), name, id[name]) Prints: 5|alice|1234\\n3|bob|4567 printf("%c is %s; %x or %X or %p; %d or %u\\n",97,a,p,p,p,j,j) Prints: a is alice; 1234abcd or 1234ABCD or 0x1234abcd; \-1 or 18446744073709551615\\n printf("2 bytes of kernel buffer at address %p: %2m", p, p) Prints: 2 byte of kernel buffer at address 0x1234abcd: printf("%4b", p) Prints (these values as binary data): 0x1234abcd printf("%#o %#x %#X\\n", 1, 2, 3) Prints: 01 0x2 0X3 printf("%#c %#c %#c\\n", 0, 9, 42) Prints: \\000 \\t * .ESAMPLE .SS "آمار (STATISTICS)" اغلب مطلوب است که آمارها به گونه‌ای جمع‌آوری شوند که از جریمه‌های قفل کردن مکرر و انحصاری متغیرهای سراسری که این اعداد در آن‌ها قرار می‌گیرند جلوگیری شود. Systemtap با استفاده از یک عملگر ویژه برای انباشت مقادیر، و چندین شبه‌تابع برای استخراج مقادیر تجمیعی آماری، راهکاری را ارائه می‌دهد. .PP عملگر تجمیع .IR <<< است و شبیه به یک انتساب یا عملیات جریان خروجی ++C است. عملوند چپ یک lvalue اسکالر یا شاخص آرایه را مشخص می‌کند که باید سراسری اعلان شده باشد. عملوند راست یک عبارت عددی است. معنای آن شهودی است: عدد داده‌شده را به انبوه اعدادی که باید آمار آن‌ها محاسبه شود اضافه کنید. (فهرست خاص آمارهایی که باید جمع‌آوری شوند به طور جداگانه توسط توابع استخراج ارائه می‌شود.) .SAMPLE foo <<< 1 stats[pid()] <<< memsize .ESAMPLE .PP توابع استخراج نیز ویژه هستند. برای هر بار استفاده از یک تابع استخراج متمایز که روی یک شناسه مشخص عمل می‌کند، مترجم ترتیب محاسبه مجموعه‌ای از آمارها را می‌دهد که آن را برآورده سازد. بدین ترتیب سیستم آمار به صورت «در صورت تقاضا» (on-demand) است. هر اجرای یک تابع استخراج باعث می‌شود که تجمیع برای آن لحظه در سراسر تمام پردازنده‌ها محاسبه شود. .PP در اینجا مجموعه توابع استخراج‌کننده آورده شده است. اولین آرگومان هر کدام همان سبک lvalue استفاده‌شده در سمت چپ عملیات انباشت است. توابع استخراج‌کننده .IR @count(v) ", " @sum(v) ", " @min(v) ", " @max(v) ", " @avg(v) ", " و @variance(v[, b]) تعداد/مجموع/حداقل/حداکثر/میانگین/واریانس تمام مقادیر انباشته‌شده را محاسبه می‌کنند. مقادیر حاصل همگی اعداد صحیح ساده هستند. آرایه‌های حاوی مقادیر تجمیعی را می‌توان مرتب کرده و روی آن‌ها پیمایش انجام داد. ساختار .BR foreach در بالا را ببینید. .PP واریانس از الگوریتم آنلاین Welford استفاده می‌کند. محاسبات مبتنی بر محاسبات اعداد صحیح است و بنابراین ممکن است از دقت پایین و سرریز رنج ببرد. برای بهبود این مورد، @variance(v[, b]) یک پارامتر اختیاری b یعنی جابجایی بیتی (bit-shift) را در محدوده 0 (پیش‌فرض) تا 62 برای مقیاس‌بندی داخلی می‌پذیرد. تنها یک مقدار جابجایی بیتی ممکن است با متغیر سراسری داده‌شده استفاده شود. مقدار جابجایی بیتی بزرگتر دقت را افزایش می‌دهد، اما احتمال سرریز را نیز بیشتر می‌کند. .SAMPLE $ stap -e \ > 'global x probe oneshot { for(i=1;i<=5;i++) x<< 'global x probe oneshot { for(i=1;i<=5;i++) x<<\fP و \fI[]\fP بتوانند روی آن‌ها استفاده شوند، دقیقاً همانند متغیر زمینه اصلی. برای مثال: .SAMPLE foo = $param->foo; printf("x:%d y:%d\\n", foo->x, foo->y) printf("my value is %d\\n", ($type == 42 ? $foo : $bar)->value) printf("my parent pid is %d\\n", task_parent(task_current())->tgid) .ESAMPLE با این حال، اگر این روش اکتشافی وابستگی برای یک اسکریپت کار نکند، استفاده از عملگر .I @cast() به مترجم می‌گوید که چگونه عدد را به عنوان یک اشاره‌گر دارای نوع تفسیر کند. .SAMPLE @cast(p, "type_name"[, "module"])\->member .ESAMPLE .PP این کار .I p را به عنوان یک اشاره‌گر به یک struct/union به نام .I type_name تفسیر کرده و مقدار .I member را ارجاع‌زدایی می‌کند. عبارات دیگر .IR \->subfield را می‌توان برای ارجاع‌زدایی سطوح بیشتر ضمیمه کرد. توجه داشته باشید که برای ارجاع‌زدایی مستقیم یک اشاره‌گر باید از {kernel,user}_{char,int,...}($p) استفاده شود (برای جزئیات بیشتر به stapfuncs(5) مراجعه کنید). .BR نکته: همان عملگر ارجاع‌زدایی .IR \-> برای اشاره به هر دوی دربرگیری مستقیم یا ارجاع غیرمستقیم اشاره‌گر استفاده می‌شود. Systemtap به طور خودکار تعیین می‌کند که کدام یک است. آرگومان اختیاری .I module به مترجم می‌گوید که کجا به دنبال اطلاعات درباره آن نوع بگردد. چندین ماژول را می‌توان به صورت یک فهرست با جداکننده‌های .IR : مشخص کرد. اگر ماژول مشخص نشده باشد، مقدار پیش‌فرض آن برای کاوشگرهای dwarf برابر با ماژول کاوشگر، یا برای توابع و سایر انواع کاوشگرها برابر با "kernel" خواهد بود. .PP پیش از این تا نسخه ۴.۲ سیستم‌تپ، در صورت عدم تعیین، "kernel" استنتاج می‌شد. از --compatible=4.2 برای فعال‌سازی این پیش‌فرض استفاده کنید. .PP مترجم می‌تواند در صورتی که debuginfo عادی در دسترس نباشد، ماژول خود را با اطلاعات نوع از یک سرآیند محصور در براکت‌های زاویه‌دار ایجاد کند. برای سرآیندهای هسته، آن را با "kernel" پیشوندگذاری کنید تا از سیستم ساخت مناسب استفاده شود. سایر سرآیندها با پارامترهای پیش‌فرض GCC در یک ماژول کاربری ساخته می‌شوند. چندین سرآیند را می‌توان به ترتیب برای حل وابستگی متقابل مشخص کرد. .PP از نسخه ۵.۴ سیستم‌تپ، سرآیند هسته "" قبل از هر سرآیند یا ماژول هسته مشخص‌شده امتحان می‌شود، که ممکن است ذکر هرگونه نام صریح فایل ماژول یا سرآیند را برای ساختارهای داده هسته غیرضروری سازد. .SAMPLE @cast(tv, "timeval", "")\->tv_sec @cast(task, "task_struct", "kernel")\->tgid @cast(task, "task_struct", "kernel")\->fs\->umask .ESAMPLE مقادیر به دست آمده توسط .BR @cast ممکن است با عملگرهای پسوندی .BR $ " و " $$ به زیبایی چاپ شوند، به همان روشی که در بخش CONTEXT VARIABLES در صفحه راهنمای .IR stapprobes (3stap) شرح داده شده است. .PP در حالت guru، مترجم به اسکریپت‌ها اجازه می‌دهد تا مقادیر جدیدی را نیز به اعضای اشاره‌گرهای تبدیل‌نوع‌شده اختصاص دهند. .PP تبدیل نوع همچنین در مورد اعضای .I void* که نوع آن‌ها ممکن است در زمان اجرا قابل تعیین باشد، مفید است. .SAMPLE probe foo { if ($var\->type == 1) { value = @cast($var\->data, "type1")\->bar } else { value = @cast($var\->data, "type2")\->baz } print(value) } .ESAMPLE .SS "کد C جاسازی‌شده (EMBEDDED C)" در حالت guru، مترجم کد C جاسازی‌شده را در سطح بالای اسکریپت می‌پذیرد. چنین کدی بین نشانگرهای .IR %{ و .IR %} محصور می‌شود و عیناً و بدون تحلیل، در دنباله‌ای مشخص به سطح بالای کد C تولیدشده منتقل می‌شود. در بیرونی‌ترین سطح، این ممکن است برای افزودن دستورالعمل‌های .IR #include و هرگونه تعاریف کمکی برای استفاده توسط سایر کدهای جاسازی‌شده مفید باشد. .PP محل دیگری که کد جاسازی‌شده در آن مجاز است، به عنوان بدنه یک تابع است. در این حالت، بدنه زبان اسکریپت به طور کامل با قطعه‌ای از کد C که مجدداً بین نشانگرهای .IR %{ " و " %} محصور شده است جایگزین می‌شود. این کد C ممکن است هر کار معقول و ایمنی را انجام دهد. تعدادی محدودیت ایمنی مستند‌نشده اما پیچیده در مورد اتمیک بودن، همزمانی، مصرف منابع، و محدودیت‌های زمان اجرا وجود دارد، بنابراین این یک تکنیک پیشرفته است. .PP مکان‌های حافظه اختصاص‌داده‌شده برای مقادیر ورودی و خروجی با استفاده از ماکروهای .IR STAP_ARG_* و .IR STAP_RETVALUE در دسترس آن قرار می‌گیرند. خطاها را می‌توان با STAP_ERROR علامت داد. خروجی را می‌توان با STAP_PRINTF نوشت. تابع ممکن است با STAP_RETURN زودتر بازگردد. در اینجا چند مثال آورده شده است: .SAMPLE function integer_ops (val) %{ STAP_PRINTF("%d\\n", STAP_ARG_val); STAP_RETVALUE = STAP_ARG_val + 1; if (STAP_RETVALUE == 4) STAP_ERROR("wrong guess: %d", (int) STAP_RETVALUE); if (STAP_RETVALUE == 3) STAP_RETURN(0); STAP_RETVALUE ++; %} function string_ops (val) %{ strlcpy (STAP_RETVALUE, STAP_ARG_val, MAXSTRINGLEN); strlcat (STAP_RETVALUE, "one", MAXSTRINGLEN); if (strcmp (STAP_RETVALUE, "three-two-one")) STAP_RETURN("parameter should be three-two-"); %} function no_ops () %{ STAP_RETURN(); /* function inferred with no return value */ %} .ESAMPLE برای اینکه این کار کند، انواع آرگومان‌های تابع و مقدار بازگشتی باید توسط مترجم از محل‌های فراخوانی استنتاج شوند. کاربر باید کد C تولیدشده برای توابع عادی زبان اسکریپت را بررسی کند تا بتواند توابع C جاسازی‌شده سازگار را بنویسد. .PP آخرین جایی که کد جاسازی‌شده در آن مجاز است، به عنوان مقدار سمت راست (rvalue) یک عبارت است. در این حالت، کد C محصور بین نشانگرهای .IR %{ " و " %} به عنوان یک مقدار عبارت عادی تفسیر می‌شود. فرض بر این است که این یک عدد ۶۴ بیتی علامت‌دار عادی است، مگر اینکه نشانگر .I /* string */ گنجانده شده باشد که در این صورت با آن به عنوان یک رشته رفتار می‌شود. .SAMPLE function add_one (val) { return val + %{ 1 %} } function add_string_two (val) { return val . %{ /* string */ "two" %} } @define SOME_STAP_MACRO %( %{ SOME_C_MACRO %} %) probe begin { printf("SOME_C_MACRO has value: %d\\n", @SOME_STAP_MACRO); } .ESAMPLE .PP کد C جاسازی‌شده ممکن است حاوی نشانگرهایی برای اثبات ویژگی‌های بهینه‌سازی و ایمنی باشد: .TP .I /* pure */ بدین معناست که کد C هیچ اثر جانبی ندارد و در صورتی که مقدار آن توسط کد اسکریپت استفاده نشود، ممکن است به طور کامل حذف شود. .TP .I /* stable */ بدین معناست که کد C همیشه دارای مقدار یکسانی است (در هر فراخوانی مشخص از گرداننده کاوشگر)، بنابراین فراخوانی‌های مکرر ممکن است به طور خودکار با مقادیر ذخیره‌شده (memoized) جایگزین شوند. چنین توابعی نباید پارامتری دریافت کنند و همچنین باید .IR pure باشند. .TP .I /* unprivileged */ بدین معناست که کد C چنان ایمن است که حتی کاربران غیرممتاز نیز مجاز به استفاده از آن هستند. .TP .I /* myproc\-unprivileged */ بدین معناست که کد C چنان ایمن است که حتی کاربران غیرممتاز نیز مجاز به استفاده از آن هستند، به شرطی که هدف کاوشگر فعلی در فرایند خود کاربر باشد. .TP .I /* guru */ بدین معناست که کد C چنان ناامن است که کاربر systemtap باید گزینه .IR \-g (حالت guru) را برای استفاده از آن مشخص کند. (تپ‌ست‌ها مجاز هستند و فرض بر این است که آن‌ها را به صورت ایمن فراخوانی می‌کنند.) .TP .I /* unmangled */ در یک تابع C جاسازی‌شده، به این معنی است که نحو دسترسی به آرگومان قدیمی (پیش از نسخه ۱.۸) باید در داخل تابع در دسترس باشد. از این رو، علاوه بر .I STAP_ARG_foo و .I STAP_RETVALUE می‌توان به ترتیب از .I THIS->foo و .I THIS->__retvalue در داخل تابع استفاده کرد. این برای مهاجرت سریع کدهای نوشته‌شده برای نسخه ۱.۷ و پیش از آن در SystemTap مفید است. .TP .I /* pragma:suffix */ انتشار کد C دربردارنده سطح فایل در نزدیکی انتهای فایل منبع C ماژول هسته حاصل. .TP .I /* unmodified-fnargs */ در یک تابع C جاسازی‌شده، بدین معناست که آرگومان‌های تابع در داخل بدنه تابع اصلاح نمی‌شوند. .TP .I /* string */ فقط در عبارات C جاسازی‌شده، بدین معناست که عبارت دارای نوع .I const char * است و باید به عنوان یک مقدار رشته‌ای رفتار شود، نه مقدار عددی پیش‌فرض long. .PP به متغیرهای سراسری سطح اسکریپت می‌توان در توابع و بلوک‌های C جاسازی‌شده دسترسی داشت. برای خواندن یا نوشتن متغیر سراسری .I var ، ابتدا باید نشانگر .I /* pragma:read:var */ یا .I /* pragma:write:var */ در تابع یا بلوک C جاسازی‌شده قرار داده شود. این کار ماکروهای .I STAP_GLOBAL_GET_* و .I STAP_GLOBAL_SET_* را برای امکان خواندن و نوشتن فراهم می‌کند. برای مثال: .SAMPLE global var global var2[100] function increment() %{ /* pragma:read:var */ /* pragma:write:var */ /* pragma:read:var2 */ /* pragma:write:var2 */ STAP_GLOBAL_SET_var(STAP_GLOBAL_GET_var()+1); //var++ STAP_GLOBAL_SET_var2(1, 1, STAP_GLOBAL_GET_var2(1, 1)+1); //var2[1,1]++ %} .ESAMPLE متغیرها را می‌توان در هر دو توابع و عبارات C جاسازی‌شده خواند و تنظیم کرد. رشته‌های بازگردانده‌شده از کد C جاسازی‌شده به اشاره‌گرها کاهش می‌یابند. متغیرها همچنین باید در سطح اسکریپت اختصاص داده شوند تا امکان استنتاج نوع فراهم شود. انتساب نقشه مقدار نوشته‌شده را برنمی‌گرداند، بنابراین زنجیره‌سازی کار نمی‌کند. .SS "توابع و ساختارهای توکار (BUILT-INS)" مجموعه‌ای از نام‌های مستعار نقاط کاوش توکار توسط اسکریپت‌های نصب‌شده در دایرکتوری مشخص‌شده در صفحه راهنمای .IR stappaths (7) ارائه شده‌اند. توابع در صفحه راهنمای .IR stapprobes (3stap) شرح داده شده‌اند. .SS "ارجاع‌زدایی (DEREFERENCING)" اعداد صحیح را می‌توان با استفاده از عملگرهای .I @kderef() یا .I @uderef() از اشاره‌گرهای ذخیره‌شده به عنوان متغیرهای عددی اسکریپت ارجاع‌زدایی کرد. عملگر .I @kderef() برای آدرس‌های فضای هسته و .I @uderef() برای آدرس‌های فضای کاربری استفاده می‌شود. .SAMPLE @kderef(SIZE, addr) @uderef(SIZE, addr) .ESAMPLE این دستور .I addr را به عنوان یک آدرس هسته/کاربر تفسیر کرده و .I SIZE بایت را با شروع از آن آدرس می‌خواند. .I SIZE باید ۱، ۲، ۴ یا ۸ بایت باشد. .SS "ثبات‌ها (REGISTERS)" مقدار ذخیره‌شده در یک ثبات را می‌توان با استفاده از عملگرهای .I @kregister() یا .I @uregister() به دست آورد. عملگر .I @kregister() برای ثبات‌های فضای هسته و .I @uregister() برای ثبات‌های فضای کاربری استفاده می‌شود. ثبات مورد نظر با استفاده از شماره DWARF آن مشخص می‌شود. .SAMPLE @kregister(0) @uregister(5) .SH "پردازش (PROCESSING)" مترجم گذر ۱ را با تجزیه اسکریپت ورودی داده‌شده و تمام اسکریپت‌های (فایل‌های با نام .IR *.stp ) موجود در دایرکتوری تپ‌ست آغاز می‌کند. دایرکتوری‌های فهرست‌شده با .BR \-I به ترتیب پردازش می‌شوند و هر یک در «حالت guru» پردازش می‌گردند. برای هر دایرکتوری، تعدادی زیردایرکتوری نیز جستجو می‌شوند. این زیردایرکتوری‌ها از نسخه هسته انتخاب‌شده (گزینه .BR \-R ) مشتق می‌شوند تا به اسکریپت‌های خاص‌تر نسخه هسته امکان دهند بر اسکریپت‌های با عمومیت بیشتر اولویت پیدا کنند. برای مثال، برای یک نسخه هسته .IR 2.6.12\-23.FC3 الگوهای زیر به ترتیب جستجو می‌شوند: .IR 2.6.12\-23.FC3/*.stp ، .IR 2.6.12/*.stp ، .IR 2.6/*.stp ، و در نهایت .IR *.stp . توقف مترجم پس از گذر ۱ باعث چاپ درخت‌های تجزیه می‌شود. .PP در گذر ۲، مترجم اسکریپت ورودی را برای حل نمادها و نوع‌ها تحلیل می‌کند. ارجاعات به متغیرها، توابع و نام‌های مستعار کاوشگر که به طور داخلی حل نشده‌اند، با جستجو در میان فایل‌های اسکریپت تپ‌ست تجزیه‌شده برآورده می‌شوند. اگر هر فایل اسکریپت تپ‌ست به این دلیل انتخاب شود که یک نماد حل‌نشده را تعریف می‌کند، کل آن فایل به صف حل مترجم اضافه می‌شود. این فرایند تا زمانی که تمام نمادها حل شوند و زیرمجموعه‌ای از فایل‌های اسکریپت تپ‌ست انتخاب شوند تکرار می‌شود. .PP سپس، تمامی توضیحات نقاط کاوش در برابر تنوع گسترده‌ای که توسط مترجم پشتیبانی می‌شود اعتبارسنجی می‌شوند. نقاط کاوشی که به مکان‌های کد ارجاع می‌دهند («نقاط کاوش همگام») نیازمند نصب اطلاعات اشکال‌زدایی مناسب هسته هستند. در گرداننده‌های کاوشگر مرتبط، متغیرهای سمت هدف (که نام آن‌ها با "$" شروع می‌شود) پیدا شده و مکان‌های زمان اجرای آن‌ها رمزگشایی می‌شود. .PP سپس، تمامی کاوشگرها و توابع برای فرصت‌های بهینه‌سازی تحلیل می‌شوند تا متغیرها، عبارات و توابعی که هیچ ارزش مفیدی و هیچ اثر جانبی ندارند حذف شوند. فرض بر این است که توابع C جاسازی‌شده دارای اثرات جانبی هستند، مگر اینکه رشته جادویی .BR /*\ pure\ */ را شامل شوند. از آنجا که این بهینه‌سازی می‌تواند خطاهای پنهان کد مانند عدم تطابق نوع یا متغیرهای زمینه $ نامعتبر را مخفی کند، گاهی اوقات ممکن است غیرفعال کردن بهینه‌سازی‌ها با گزینه .BR \-u مفید باشد. .PP در نهایت، انواع تمامی متغیرها، توابع، پارامترها، آرایه‌ها و شاخص‌ها از زمینه (مقادیر متنی و عملگرها) استنتاج می‌شوند. توقف مترجم پس از گذر ۲ باعث می‌شود تمام کاوشگرها، توابع و متغیرها را به همراه تمام انواع استنتاج‌شده فهرست کند. هرگونه نوع ناسازگار یا حل‌نشده موجب بروز خطا می‌شود. .PP در گذر ۳، مترجم کد C را می‌نویسد که بیانگر اقدامات تمام فایل‌های اسکریپت انتخاب‌شده است، و یک .IR Makefile برای ساخت آن در قالب یک شیء هسته ایجاد می‌کند. این فایل‌ها در یک دایرکتوری موقت قرار می‌گیرند. توقف مترجم در این نقطه باعث چاپ محتوای فایل C می‌شود. .PP در گذر ۴، مترجم سیستم ساخت هسته لینوکس را فراخوانی می‌کند تا فایل شیء هسته واقعی را بسازد. این کار مستلزم اجرای .IR make در دایرکتوری موقت است و نیازمند نصب سیستم ساخت ماژول هسته (سرآیندها، پیکربندی و Makefileها) در محل معمول .IR /lib/modules/VERSION/build است. توقف مترجم پس از گذر ۴ آخرین فرصت قبل از اجرای شیء هسته است. این ممکن است در صورتی که بخواهید فایل را آرشیو کنید مفید باشد. .PP در گذر ۵، مترجم برنامه کمکی systemtap به نام .I staprun را برای شیء هسته داده‌شده فراخوانی می‌کند. این برنامه ترتیبی می‌دهد تا ماژول بارگذاری شده و سپس با آن ارتباط برقرار کند و داده‌های ردیابی را از هسته در فایل‌های موقت کپی کند، تا زمانی که کاربر سیگنال وقفه ارسال کند. هرگونه خطای زمان اجرا که توسط گرداننده‌های کاوشگر با آن مواجه شود، مانند کمبود حافظه، تقسیم بر صفر، فراتر رفتن از محدودیت‌های تودرتویی یا زمان اجرا، منجر به یک نشانگر خطای نرم می‌شود. خطاهای نرم بیش از MAXERRORS تمام کاوشگرهای بعدی (به جز کاوشگرهای مدیریت خطا) را مسدود کرده و نشست را خاتمه می‌دهند. در نهایت، .I staprun ماژول را تخلیه کرده و پاکسازی را انجام می‌دهد. .SS "خاتمه غیرعادی (ABNORMAL TERMINATION)" باید از کشتن اجباری فرایند stap، مثلاً با SIGKILL خودداری کرد، زیرا فرایند stapio (یک فرایند فرزند از فرایند stap) و ماژول بارگذاری‌شده ممکن است روی سیستم در حال اجرا باقی بمانند. اگر این اتفاق افتاد، SIGTERM یا SIGINT را به هر فرایند باقی‌مانده stapio ارسال کنید، سپس از rmmod برای تخلیه ماژول systemtap استفاده کنید. .SH "مثال‌ها (EXAMPLES)" برای مجموعه‌ای مختصر از نمونه‌ها به صفحه راهنمای .IR stapex (3stap) مراجعه کنید، یا به مجموعه بزرگی از نمونه‌های نصب‌شده در دایرکتوری‌های مستندات/مجموعه آزمون (testsuite) ابزار systemtap مراجعه نمایید. برای محل احتمالی این موارد در سیستم به .IR stappaths (7stap) مراجعه فرمایید. .SH "حافظه موقت (CACHING)" مترجم systemtap خروجی گذر ۳ (کد C تولیدشده) و خروجی گذر ۴ (ماژول کامپایل‌شده هسته) را در صورت موفقیت‌آمیز بودن گذر ۴ کش می‌کند. اگر همان اسکریپت مجدداً با فرض برقراری همان شرایط (همان نسخه هسته، همان نسخه systemtap و غیره) ترجمه شود، از این خروجی کش‌شده مجدداً استفاده می‌شود. فایل‌های کش‌شده در دایرکتوری .I $SYSTEMTAP_DIR/cache ذخیره می‌شوند. حافظه موقت را می‌توان با قرار دادن فایل .I cache_mb_limit در دایرکتوری کش (نشان‌داده‌شده در بالا) محدود کرد که فقط شامل یک عدد صحیح ASCII است که نشان می‌دهد حافظه موقت نباید از چند مگابایت (MiB) تجاوز کند. در صورت عدم وجود این فایل، یک پیش‌فرض با محدودیت ۲۵۶ مگابایت ایجاد می‌شود. این یک محدودیت «نرم» است به این معنا که اگر بازه پاکسازی کش سپری شده باشد، پس از افزودن یک ورودی جدید حافظه موقت پاکسازی خواهد شد، بنابراین کل حجم کش ممکن است موقتاً از این مقدار بیشتر شود. این بازه را می‌توان با قرار دادن فایل .I cache_clean_interval_s در دایرکتوری کش مشخص کرد که فقط حاوی یک عدد صحیح ASCII به عنوان بازه زمانی به ثانیه است. در صورت نبود این فایل، یک پیش‌فرض با بازه ۳۰۰ ثانیه ایجاد خواهد شد. .SH "ایمنی و امنیت (SAFETY AND SECURITY)" .PP ابزار Systemtap ممکن است به عنوان یک ابزار مدیریتی قدرتمند استفاده شود. این ابزار می‌تواند ساختارهای داده داخلی هسته و اطلاعات بالقوه خصوصی کاربر را آشکار کند. (در حالت زمان اجرای .BR dyninst این‌گونه نیست، بخش .I "زمان‌های اجرای جایگزین (ALTERNATE RUNTIMES)" را در ادامه ببینید.) مترجم محدودیت‌های ایمنی بسیاری را در طول کامپایل و موارد بیشتری را در طول زمان اجرا اعمال می‌کند. هدف آن اطمینان از این است که هیچ زیرروال گرداننده‌ای نتواند برای مدت بسیار طولانی اجرا شود، حافظه بی‌پایان تخصیص دهد، عملیات ناامن انجام دهد، یا به طور ناخواسته با سیستم تداخل پیدا کند. استفاده از متغیرهای سراسری اسکریپت به طور خودکار به صورت مناسب با قفل خواندن/نوشتن محافظت می‌شود تا در برابر دستکاری توسط گرداننده‌های همزمان کاوشگر محافظت گردد. قفل‌ها به گونه‌ای گرفته می‌شوند که بخش دستکاری متغیر سراسری در گرداننده‌های کاوشگر به طور اتمیک اجرا شود (قفل‌ها به صورت همه-یا-هیچ گرفته می‌شوند). بن‌بست‌ها با مهلت‌های زمانی تشخیص داده می‌شوند. از فلگ .BR \-t برای دریافت گزارش‌های مربوط به رقابت بیش از حد قفل استفاده کنید. بنابراین آزمایش با اسکریپت‌ها به طور کلی .BR ایمن است. گزینه حالت guru یعنی .B \-g به مدیران اجازه می‌دهد تا اکثر اقدامات ایمنی را دور بزنند، که این امر اجازه عملیات تهاجمی یا تغییر وضعیت، کد C جاسازی‌شده را می‌دهد و خطر اختلال را افزایش می‌دهد. به صورت پیش‌فرض، پیشگیری از اضافه بار (overload prevention) برای تمام ماژول‌ها روشن است. اگر مایل به غیرفعال کردن پردازش اضافه‌بار هستید، از گزینه .BR \-\-suppress\-time\-limits استفاده کنید. خطاهایی که در زمان اجرا شناسایی می‌شوند معمولاً منجر به خاموش شدن تمیز اسکریپت و یک پیام خطای گذر ۵ می‌شوند. گزینه .BR \-\-suppress\-handler\-errors به اسکریپت‌ها اجازه می‌دهد تا خطاهای نرم را بدون خاموش شدن تحمل کنند. .SS "مجوزها (PERMISSIONS)" برای زمان اجرای عادی ماژول هسته لینوکس، جهت اجرای اشیاء هسته‌ای که systemtap می‌سازد، کاربر باید یکی از موارد زیر باشد: .IP \(bu 4 کاربر ریشه (root)؛ .IP \(bu 4 عضوی از گروه‌های .I stapdev و .I stapusr ؛ .IP \(bu 4 عضوی از گروه‌های .I stapsys و .I stapusr ؛ یا .IP \(bu 4 عضوی از گروه .I stapusr . .PP کاربر ریشه یا کاربری که عضو هر دو گروه .I stapdev و .I stapusr است می‌تواند هر اسکریپت systemtap را بسازد و اجرا کند. .PP کاربری که عضو هر دو گروه .I stapsys و .I stapusr است تنها در شرایط زیر می‌تواند از ماژول‌های از پیش ساخته‌شده استفاده کند: .IP \(bu 4 ماژول توسط یک امضاکننده معتمد امضا شده باشد. امضاکنندگان معتمد معمولاً سرورهای کامپایل systemtap هستند که در صورت مشخص شدن گزینه \fI\-\-privilege\fR توسط کلاینت، ماژول‌ها را امضا می‌کنند. برای اطلاعات بیشتر به صفحه راهنمای .IR stap\-server (8) مراجعه کنید. .IP \(bu 4 ماژول با استفاده از گزینه‌های \fI\-\-privilege=stapsys\fR یا \fI\-\-privilege=stapusr\fR ساخته شده باشد. .PP اعضای فقط گروه .I stapusr تنها تحت شرایط زیر می‌توانند از ماژول‌های از پیش ساخته‌شده استفاده کنند: .IP \(bu 4 ماژول در دایرکتوری /lib/modules/VERSION/systemtap قرار داشته باشد. این دایرکتوری باید متعلق به کاربر root بوده و برای همگان قابل نوشتن نباشد. .PP یا .IP \(bu 4 ماژول توسط یک امضاکننده معتمد امضا شده باشد. امضاکنندگان معتمد معمولاً سرورهای کامپایل systemtap هستند که در صورت تعیین گزینه \fI\-\-privilege\fR توسط کلاینت ماژول‌ها را امضا می‌کنند. برای اطلاعات بیشتر به صفحه راهنمای .IR stap\-server (8) مراجعه کنید. .IP \(bu 4 ماژول با استفاده از گزینه \fI\-\-privilege=stapusr\fR ساخته شده باشد. .PP ماژول‌های هسته تولیدشده توسط برنامه .I stap توسط برنامه .IR staprun اجرا می‌شوند. برنامه اخیر بخشی از بسته Systemtap است که به بارگذاری و تخلیه ماژول (اما فقط در منطقه سفید) و انتقال داده‌ها از هسته به کاربر اختصاص دارد. از آنجا که .IR staprun هیچ بررسی امنیتی اضافی روی اشیاء هسته‌ای که به آن داده می‌شود انجام نمی‌دهد، اضافه کردن کاربران غیرقابل اعتماد به گروه‌های .I stapdev یا .I stapusr توسط مدیر سیستم کاری غیرعاقلانه خواهد بود. .SS "بوت امن (SECUREBOOT)" اگر در سیستم فعلی قابلیت SecureBoot در سفت‌افزار UEFI روشن باشد، تمام ماژول‌های هسته باید امضا شوند. (برخی هسته‌ها ممکن است اجازه دهند مدت‌ها پس از بوت با یک توالی کلید مانند SysRq-X قابلیت SecureBoot غیرفعال شود، که امضای ماژول‌ها را غیرضروری می‌کند.) دو روش برای امضای ماژول systemtap وجود دارد. سرور کامپایل systemtap می‌تواند ماژول‌ها را با یک MOK (کلید مالک دستگاه) که با سیستم کلاینت مشترک است امضا کند. برای مثال: .SAMPLE stap \-\-use-server=HOSTNAME:PORT \-e 'SCRIPT' # اگر کلید mok مشترکی با فهرست کلیدهای mok سرور systemtap # و پایگاه‌داده mok کلاینت وجود نداشته باشد، کاربر توسط stap هدایت می‌شود تا دستور زیر را فراخوانی کند: sudo mokutil --import signing_key.x509 # سپس پس از راه‌اندازی مجدد سیستم: stap \-\-use-server=HOSTNAME:PORT \-e 'SCRIPT' # از سرور برای ساخت و امضای ماژول استفاده می‌کند و ماژول روی کلاینت اجرا خواهد شد .ESAMPLE روش دیگر برای امضای ماژول‌ها استفاده از گزینه \fI\-\-sign-module\fR در stap است که از یک MOK در سیستم کلاینت بدون استفاده از سرور استفاده می‌کند. برای مثال: .SAMPLE stap \-\-sign-module \-e 'SCRIPT' # اگر کلید mok مربوط به systemtap در پایگاه‌داده mok سیستم وجود نداشته باشد # کاربر توسط stap هدایت می‌شود تا دستور زیر را فراخوانی کند: sudo mokutil --import \ /home/USER/.systemtap/ssl/server/moks/FINGERPRINT/signing_key.x509 # سپس پس از راه‌اندازی مجدد سیستم: stap \-\-sign-module \-e 'SCRIPT' # ماژول را امضا کرده و اجرا می‌کند .ESAMPLE برای جزئیات بیشتر به صفحه ویکی زیر مراجعه کنید: .PP .RS .nh .BR https://sourceware.org/systemtap/wiki/SecureBoot .hy .RE برخی از هسته‌ها به systemtap اجازه نمی‌دهند حدس بزند که آیا امضای ماژول در حال اجرا است یا خیر. در چنین ماشین‌هایی، متغیر محیطی SYSTEMTAP_SIGN را هنگام اجرای stap روی هر مقداری تنظیم کنید. .SS "محدودیت‌های منابع (RESOURCE LIMITS)" بسیاری از محدودیت‌های استفاده از منابع توسط ماکروها در کد C تولیدشده تنظیم می‌شوند. این موارد را می‌توان با فلگ‌های .BR \-D لغو کرد. گزیده‌ای از این موارد به شرح زیر است: .TP MAXNESTING حداکثر تعداد فراخوانی‌های توابع تو در تو. پیش‌فرض با تحلیل اسکریپت تعیین می‌شود، همراه با ۱۰ شکاف جایزه که برای اسکریپت‌های بازگشتی اضافه می‌شود. .TP MAXSTRINGLEN حداکثر طول رشته‌ها، پیش‌فرض ۱۲۸. .TP MAXTRYLOCK حداکثر تعداد تکرارها برای انتظار قفل‌ها روی متغیرهای سراسری پیش از اعلام بن‌بست احتمالی و رد کردن کاوشگر، پیش‌فرض ۱۰۰۰. .TP MAXACTION حداکثر تعداد دستورات برای اجرا در طول هر اصابت کاوشگر تکی (با وقفه‌های غیرفعال)، پیش‌فرض ۱۰۰۰. توجه داشته باشید که برای گرداننده‌های کاوشگر مستقیم و فاقد حلقه یا بازگشت، به دلیل بهینه‌سازی، این پارامتر ممکن است بیش از حد محافظه‌کارانه تفسیر شود. .TP MAXACTION_INTERRUPTIBLE حداکثر تعداد دستورات برای اجرا در طول هر اصابت کاوشگر تکی که با وقفه‌های فعال اجرا می‌شود (مانند کاوشگرهای begin/end)، پیش‌فرض (MAXACTION * 10). .TP MAXBACKTRACE حداکثر تعداد فریم‌های پشته که توسط بازکننده پشته زمان اجرای stap پردازش می‌شوند، همان‌طور که توسط توابع backtrace در تپ‌ست‌های [u]context-unwind.stp تولید می‌شود، پیش‌فرض ۲۰. .TP MAXMAPENTRIES حداکثر تعداد ردیف‌ها در هر آرایه سراسری منفرد، پیش‌فرض ۲۰۴۸. آرایه‌های جداگانه را می‌توان در عوض با یک محدودیت بزرگتر یا کوچکتر اعلان کرد: .SAMPLE global big[10000],little[5] .ESAMPLE یا با .IR % مشخص کرد تا به طور خودکار بچرخند (جایگزینی ورودی‌های قدیمی)، مانند .SAMPLE global big% .ESAMPLE یا هر دو. .TP MAPHASHBIAS تعداد توان‌های ۲ برای اضافه یا کم کردن از اندازه طبیعی جدول درهم‌سازی پشتیبان هر آرایه انجمنی سراسری. پیش‌فرض 0 است. اعداد مثبت کوچک را برای به دست آوردن کارایی بیشتر به قیمت مصرف حافظه بیشتر امتحان کنید، زیرا این کار باید برخوردهای جدول درهم‌سازی را کاهش دهد. اعداد منفی کوچک را برای معاوضه معکوس امتحان کنید. .TP MAXERRORS حداکثر تعداد خطاهای نرم پیش از خروج، پیش‌فرض 0، به این معنی که اولین خطا باعث خروج از اسکریپت می‌شود. توجه داشته باشید که با گزینه .B \-\-suppress\-handler\-errors ، این محدودیت اعمال نمی‌شود. .TP MAXSKIPPED حداکثر تعداد کاوشگرهای ردشده پیش از خروج، پیش‌فرض ۱۰۰. اجرای systemtap با حالت \-t (زمان‌بندی) جزئیات بیشتری درباره کاوشگرهای ردشده ارائه می‌دهد. با تنظیم پیش‌فرض \-DINTERRUPTIBLE=1، کاوشگرهایی که به دلیل ورود مجدد رد شده‌اند در این محدودیت جمع نمی‌شوند. توجه داشته باشید که با گزینه .B \-\-suppress\-handler\-errors ، این محدودیت اعمال نمی‌شود. .TP MINSTACKSPACE حداقل بایت‌های پشته هسته آزاد مورد نیاز برای اجرای یک گرداننده کاوشگر، پیش‌فرض ۱۰۲۴. این عدد باید برای نیازهای خود گرداننده کاوشگر، به علاوه یک حاشیه ایمنی، به اندازه کافی بزرگ باشد. .TP MAXUPROBES حداکثر تعداد کاوشگرهای فضای کاربر (uprobes) مسلح همزمان، پیش‌فرض تا حدودی بزرگتر از تعداد نقاط کاوش فضای کاربر نام‌برده در اسکریپت است. این استخر باید به طور بالقوه بزرگ باشد زیرا اشیاء مجزای uprobe (هر کدام حدود ۶۴ بایت) برای هر فرایند به ازای هر کاوشگر منطبق در سطح اسکریپت تخصیص داده می‌شوند. .TP STP_MAXMEMORY حداکثر مقدار حافظه (به کیلوبایت) که ماژول systemtap باید استفاده کند، پیش‌فرض نامحدود است. اندازه حافظه شامل اندازه خود ماژول به علاوه هرگونه تخصیص اضافی است. این فقط تخصیص‌های مستقیم توسط زمان اجرای systemtap را ردیابی می‌کند. این تخصیص‌های غیرمستقیم (مانند موارد انجام‌شده توسط اجزای داخلی kprobes/uprobes و غیره) را ردیابی نمی‌کند. .TP STP_OVERLOAD_THRESHOLD, STP_OVERLOAD_INTERVAL حداکثر تعداد چرخه‌های ماشین صرف‌شده در کاوشگرها روی هر پردازنده در بازه داده‌شده، پیش از اینکه وضعیت اضافه‌بار اعلام شود و اسکریپت خاموش گردد. مقادیر پیش‌فرض ۵۰۰ میلیون و ۱ میلیارد هستند تا مصرف پردازنده اسکریپت stap را در حدود ۵۰٪ محدود کنند. .TP STP_PROCFS_BUFSIZE اندازه بافرهای خواندن کاوشگر procfs (به بایت). مقدار پیش‌فرض برابر با .IR MAXSTRINGLEN است. این مقدار را می‌توان بر مبنای هر فایل procfs با استفاده از پارامتر کاوشگر خواندن procfs یعنی .I .maxsize(MAXSIZE) لغو کرد. .PP در اسکریپت‌هایی که شامل کاوشگرهایی در هر مسیر وقفه هستند، ممکن است این وقفه‌ها در وسط گرداننده کاوشگر دیگری رخ دهند. در این حالت کاوشگر در گرداننده وقفه رد می‌شود تا از ورود مجدد جلوگیری شود. برای رفع این مشکل، stap را با گزینه .BR \-DINTERRUPTIBLE=0 اجرا کنید تا وقفه‌ها در سرتاسر گرداننده کاوشگر ماسک شوند. این کار مقداری سربار اضافی به کاوشگرها اضافه می‌کند، اما ممکن است از ورود مجدد در موارد مشکل‌ساز رایج جلوگیری کند. با این حال، کاوشگرها در گرداننده‌های NMI و در مسیر فراخوانی زمان اجرای stap ممکن است همچنان به دلیل ورود مجدد رد شوند. .PP در صورتی که پس از شروع اجرای کاوشگر مشکلی برای .IR stap " یا " staprun پیش بیاید، می‌توان هر دو فرایند کاربری را با ایمنی متوقف کرد و ماژول هسته کاوشگر فعال را با .IR rmmod حذف نمود. هرگونه پیام ردیابی معلق ممکن است از دست برود. .SH "کاربران غیرممتاز (UNPRIVILEGED USERS)" .PP ابزار Systemtap ساختارهای داده داخلی هسته و اطلاعات بالقوه خصوصی کاربر را آشکار می‌سازد. به همین دلیل، استفاده از تمام قابلیت‌های systemtap به کاربر ریشه (root) و کاربرانی که عضو گروه‌های stapdev و stapusr هستند محدود شده است. با این حال، مجموعه‌ای محدود از ویژگی‌های systemtap می‌تواند در دسترس کاربران مورد اعتماد و غیرممتاز قرار گیرد. این کاربران تنها عضو گروه stapusr، یا عضو گروه‌های stapusr و stapsys هستند. این کاربران می‌توانند ماژول‌های systemtap را که توسط یک سرور کامپایل معتمد systemtap کامپایل و تأیید شده‌اند، بارگذاری کنند. توضیحات گزینه‌های \fI\-\-privilege\fR و \fI\-\-use\-server\fR را ببینید. برای اطلاعات درباره راه‌اندازی سرور کامپایل معتمد به فایل \fIREADME.unprivileged\fR در کد منبع systemtap مراجعه کنید. محدودیت‌های اعمال‌شده هنگام تعیین \fI\-\-privilege=stapsys\fR به گونه‌ای طراحی شده‌اند که از اقدامات زیر توسط کاربران غیرممتاز جلوگیری کنند: .RS .IP \(bu 4 آسیب رساندن مخرب به سیستم. .RE محدودیت‌های اعمال‌شده هنگام تعیین \fI\-\-privilege=stapusr\fR به گونه‌ای طراحی شده‌اند که از اقدامات زیر توسط کاربران غیرممتاز جلوگیری کنند: .RS .IP \(bu 4 آسیب رساندن مخرب به سیستم. .IP \(bu 4 دسترسی به اطلاعاتی که معمولاً در دسترس یک کاربر غیرممتاز نیست. .IP \(bu 4 مختل کردن کارایی فرایندهای متعلق به سایر کاربران سیستم. مقداری سربار برای کل سیستم به طور کلی اجتناب‌ناپذیر است زیرا کاوشگرهای کاربر غیرممتاز در زمان‌های مناسب فعال می‌شوند. آنچه می‌خواهیم از آن جلوگیری کنیم وقفه هدفمند در فرایندهای کاربر دیگر است که معمولاً توسط یک کاربر غیرممتاز امکان‌پذیر نیست. .RE .SS "محدودیت‌های کاوشگر (PROBE RESTRICTIONS)" عضوی از گروه‌های stapusr و stapsys می‌تواند از تمام نقاط کاوش استفاده کند. .PP عضوی که فقط در گروه stapusr است می‌تواند تنها از کاوشگرهای زیر استفاده کند: .RS .IP \(bu 4 begin, begin(n) .IP \(bu 4 end, end(n) .IP \(bu 4 error(n) .IP \(bu 4 never .IP \(bu 4 process.*، در جایی که فرایند هدف متعلق به خود کاربر باشد. .IP \(bu 4 timer.{jiffies,s,sec,ms,msec,us,usec,ns,nsec}(n)* .IP \(bu 4 timer.hz(n) .RE .SS "محدودیت‌های زبان اسکریپت (SCRIPT LANGUAGE RESTRICTIONS)" ویژگی‌های زبان اسکریپت‌نویسی زیر برای تمام کاربران غیرممتاز غیرقابل دسترس است: .RS .IP \(bu 4 هر ویژگی‌ای که توسط گزینه حالت گورو (\-g) فعال شود. .IP \(bu 4 کد C جاسازی‌شده. .RE .SS "محدودیت‌های زمان اجرا (RUNTIME RESTRICTIONS)" محدودیت‌های زمان اجرای زیر برای تمام کاربران غیرممتاز اعمال می‌شود: .RS .IP \(bu 4 تنها کد زمان اجرای پیش‌فرض (گزینه \fI-R\fR را ببینید) می‌تواند استفاده شود. .RE محدودیت‌های اضافی برای اعضای فقط گروه stapusr اعمال می‌شود: .RS .IP \(bu 4 کاوش فرایندهای متعلق به سایر کاربران مجاز نیست. .IP \(bu 4 دسترسی به حافظه هسته (خواندن و نوشتن) مجاز نیست. .RE .SS "محدودیت‌های گزینه‌های خط فرمان (COMMAND LINE OPTION RESTRICTIONS)" برخی از گزینه‌های خط فرمان دسترسی به ویژگی‌هایی را فراهم می‌کنند که نباید برای تمام کاربران غیرممتاز در دسترس باشد: .RS .IP \(bu 4 گزینه \-g نباید مشخص شود. .IP \(bu 4 گزینه‌های زیر نباید توسط کلاینت سرور کامپایل استفاده شوند: .SAMPLE \-a, \-B, \-D, \-I, \-r, \-R .ESAMPLE .RE .SS "محدودیت‌های محیط (ENVIRONMENT RESTRICTIONS)" متغیرهای محیطی زیر نباید برای تمام کاربران غیرممتاز تنظیم شوند: .SAMPLE SYSTEMTAP_RUNTIME SYSTEMTAP_TAPSET SYSTEMTAP_DEBUGINFO_PATH .ESAMPLE .SS "محدودیت‌های تَپ‌ست (TAPSET RESTRICTIONS)" به طور کلی، توابع تپ‌ست تنها زمانی برای اعضای گروه stapusr در دسترس هستند که اطلاعاتی را جمع‌آوری نکنند که یک برنامه عادی اجراشده با دسترسی‌های آن کاربر از دسترسی به آن‌ها محروم باشد. دو دسته از توابع تپ‌ست غیرممتاز وجود دارد. دسته اول شامل توابع کاربردی است که بدون قید و شرط در دسترس همه کاربران قرار دارند؛ این موارد شامل چیزهایی مانند زیر است: .SAMPLE cpu:long () exit () str_replace:string (prnt_str:string, srch_str:string, rplc_str:string) .ESAMPLE دسته دوم شامل توابع اصطلاحاً .I myproc-unprivileged است که تنها می‌توانند اطلاعات درون فرایندهای خود کاربر را جمع‌آوری کنند. اسکریپت‌هایی که مایل به استفاده از این توابع هستند باید نتیجه تابع تپ‌ست \fIis_myproc\fR را آزمایش کنند و تنها در صورتی این توابع را فراخوانی کنند که نتیجه 1 باشد. اگر هر یک از این توابع توسط یک کاربر غیرممتاز درون یک کاوشگر در فرایندی که متعلق به آن کاربر نیست فراخوانی شود، اسکریپت بلافاصله خارج خواهد شد. نمونه‌هایی از توابع .I myproc-unprivileged عبارتند از: .SAMPLE print_usyms (stk:string) user_int:long (addr:long) usymname:string (addr:long) .ESAMPLE هنگامی که هر تابعی که در هیچ‌یک از دسته‌های بالا قرار ندارد توسط اعضای فقط گروه stapusr استفاده شود، یک خطای کامپایل ایجاد می‌شود. هیچ تابع تپ‌ست توکار دیگری نباید توسط اعضای فقط گروه stapusr استفاده شود. .SH "زمان‌های اجرای جایگزین (ALTERNATE RUNTIMES)" .PP همان‌طور که در بالا شرح داده شد، حالت زمان اجرای پیش‌فرض systemtap شامل ساخت و بارگذاری ماژول‌های هسته است که ملاحظات امنیتی مختلفی را به همراه دارد. Systemtap اکنون شامل دو پیش‌زمینه (backend) نمونه اولیه جدید است: \fI\-\-runtime=dyninst\fR و \fI\-\-runtime=bpf\fR. گزینه \fI\-\-runtime=dyninst\fR از Dyninst برای ابزار دقیق کردن فرایندهای خود کاربر در زمان اجرا استفاده می‌کند. این پیش‌زمینه از ماژول‌های هسته استفاده نمی‌کند و نیازی به مجوزهای ریشه ندارد، اما نسبت به انواع کاوشگرها و سایر ساختارهایی که یک اسکریپت می‌تواند استفاده کند محدود است. زمان اجرای \fIdyninst\fR در حالت اتصال به هدف عمل می‌کند، بنابراین نیازمند یک فرایند با \fI\-c COMMAND\fR یا \fI\-x PID\fR است. برای مثال: .SAMPLE stap \-\-runtime=dyninst \-c 'stap \-V' \ \-e 'probe process.function("main") { println("hi from dyninst!") }' .ESAMPLE ممکن است غیرفعال کردن یک بررسی متداخل selinux با دستور زیر لازم باشد: .SAMPLE # setsebool allow_execstack 1 .ESAMPLE گزینه \fI\-\-runtime=bpf\fR اسکریپت کاربر را به‌جای ماژول هسته به برنامه‌های فیلتر بسته برکلی توسعه‌یافته (eBPF) کامپایل می‌کند. برنامه‌های eBPF توسط هسته از نظر ایمنی تأیید می‌شوند و توسط یک ماشین مجازی درون هسته اجرا می‌گردند. این زمان اجرا در مراحل اولیه توسعه است و در حال حاضر فاقد پشتیبانی از تعدادی از ویژگی‌های موجود در زمان اجرای پیش‌فرض است. لطفاً برای اطلاعات بیشتر به صفحه راهنمای \fIstapbpf\fR(8) مراجعه فرمایید. .SH "وضعیت خروج (EXIT STATUS)" مترجم systemtap معمولاً در صورتی که اسکریپت درخواستی با موفقیت تا گذر درخواستی پردازش و اجرا شده باشد با کد موفقیت 0 بازمی‌گردد. در غیر این صورت، خطاها ممکن است در stderr چاپ شوند و یک کد خرابی برگردانده شود. از .I \-v یا .I \-vp N برای افزایش سطح پرگویی (سراسری یا بر مبنای هر گذر) جهت شناسایی منبع مشکل استفاده کنید. در حالت فهرست‌بندی .RI ( \-l " و " \-L )، پیام‌های خطا معمولاً سرکوب می‌شوند. در صورتی که حداقل یک کاوشگر منطبق پیدا شود، کد موفقیت 0 برگردانده می‌شود. اسکریپتی که در گذر ۵ اجرا می‌شود و با ^C / SIGINT متوقف می‌شود، موفقیت‌آمیز در نظر گرفته می‌شود. .SH "منسوخ‌شدگی (DEPRECATION)" با گذشت زمان، ممکن است برخی از ویژگی‌های زبان اسکریپت و کتابخانه تپ‌ست دستخوش تغییرات ناسازگاری شوند، به‌طوری که اسکریپت نوشته‌شده برای نسخه قدیمی systemtap دیگر اجرا نشود. در این موارد، اجرای systemtap با فلگ .I \-\-compatible VERSION و مشخص کردن آخرین نسخه کارآمد شناخته‌شده ممکن است کمک کند. اجرای systemtap با فلگ .I \-\-check\-version در صورتی که هرگونه عنصر بالقوه ناسازگار تجزیه شده باشد، یک هشدار صادر می‌کند. جزئیات تاریخی منسوخ‌شدگی را می‌توان در فایل NEWS یافت. هدف از امکانات منسوخ‌شدگی، بهبود تجربه اسکریپت‌های نوشته‌شده برای نسخه‌های جدیدتر systemtap است (با افزودن جایگزین‌های بهتر و حذف گزینه‌های قدیمی متعارض یا نامرتب)، در حالی که همزمان به اسکریپت‌های نوشته‌شده برای نسخه‌های قدیمی‌تر systemtap اجازه می‌دهد به کار خود ادامه دهند. بنابراین منسوخ‌شدگی به عنوان یک .I خدمت به کاربران (و یک زحمت برای توسعه‌دهندگان systemtap) در نظر گرفته شده است، نه برعکس. لطفاً توجه داشته باشید که شناسه‌های دارای پیشوند خط زیرین (_) در تپ‌ست گاهی اوقات دستخوش چنان تغییراتی می‌شوند که حفظ سازگاری برای آن‌ها حتی با سازوکارهای منسوخ‌شدگی دشوار است. از اتکا به این موارد در اسکریپت‌های خود خودداری کنید؛ در عوض ارتقای آن‌ها را به وضعیت بدون خط زیرین پیشنهاد دهید. .SH "فایل‌ها (FILES)" .TP فایل‌های مهم و مسیرهای متناظر آن‌ها را می‌توان در صفحه راهنمای .IR stappaths (7) یافت. .SH "همچنین ببینید (SEE ALSO)" .nh .nf .IR stapprobes (3stap), .IR function::* (3stap), .IR probe::* (3stap), .IR tapset::* (3stap), .IR stappaths (7), .IR staprun (8), .IR stapdyn (8), .IR systemtap (8), .IR stapvars (3stap), .IR stapex (3stap), .IR stap\-server (8), .IR stap\-prep (1), .IR stapref (1), .IR awk (1), .IR gdb (1) .SH "اشکالات (BUGS)" از پیوند Bugzilla در صفحه وب پروژه یا فهرست پستی ما استفاده کنید: .nh .BR http://sourceware.org/systemtap ", " . .hy .PP .IR error::reporting (7stap), .nh .BR https://sourceware.org/systemtap/wiki/HowToReportBugs .hy