'\" t
.\"     Title: perf-script-perl
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net>
.\"      Date: 09/04/2026
.\"    Manual: perf Manual
.\"    Source: perf
.\"  Language: Persian
.\"
.TH "PERF\-SCRIPT\-PERL" "1" "09/04/2026" "perf" "perf Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "نام (NAME)"
perf\-script\-perl \- پردازش داده‌های ردگیری با استفاده از اسکریپت Perl
.SH "خلاصه دستور (SYNOPSIS)"
.sp
.nf
\fIperf script\fR [\-s [Perl]:script[\&.pl] ]
.fi
.SH "توضیحات (DESCRIPTION)"
.sp
این گزینه از \fIperf script\fR برای پردازش داده‌های \fIperf script\fR با استفاده از مفسر درون‌ساخت Perl در perf استفاده می‌شود\&. این ابزار فایل ورودی را خوانده و پردازش می‌کند و در صورت وجود، نتایج تحلیل ردگیری پیاده‌سازی‌شده در اسکریپت Perl مشخص‌شده را نمایش می‌دهد\&.
.SH "اسکریپت‌های آغازین (STARTER SCRIPTS)"
.sp
می‌توانید با اجرای دستور \fIperf script \-g perl\fR در همان دایرکتوری که فایل ردگیری perf\&.data موجود است، از خواندن ادامه این سند صرف‌نظر کنید\&. این دستور یک اسکریپت آغازین حاوی یک گرداننده برای هر یک از انواع رویدادهای موجود در فایل ردگیری تولید می‌کند؛ این اسکریپت صرفاً تمام فیلدهای موجود را برای هر رویداد در فایل ردگیری چاپ می‌کند\&.
.sp
همچنین می‌توانید برای مشاهده مثال‌های معمول از نحوه انجام کارهای پایه مانند تجمیع داده‌های رویداد، چاپ نتایج و غیره، به اسکریپت‌های موجود در مسیر ~/libexec/perf\-core/scripts/perl نگاهی بیندازید\&. علاوه بر این، اسکریپت check\-perf\-script\&.pl هرچند از نظر نتایج جالب توجه نیست، اما تلاش می‌کند تمام قابلیت‌های اصلی اسکریپت‌نویسی را به کار گیرد\&.
.SH "گرداننده‌های رویداد (EVENT HANDLERS)"
.sp
هنگامی که \fIperf script\fR با استفاده از یک اسکریپت ردگیری فراخوانی می‌شود، یک \fIتابع گرداننده\fR تعریف‌شده توسط کاربر برای هر رویداد در ردگیری فراخوانی می‌گردد\&. اگر هیچ تابع گرداننده‌ای برای یک نوع رویداد مشخص تعریف نشده باشد، آن رویداد نادیده گرفته می‌شود (یا به تابع \fItrace_unhandled\fR ارسال می‌شود، به پایین مراجعه کنید) و رویداد بعدی پردازش می‌گردد\&.
.sp
بیشتر مقادیر فیلدهای رویداد به عنوان آرگومان به تابع گرداننده ارسال می‌شوند؛ برخی از فیلدهای کم‌کاربردتر ارسال نمی‌شوند \- این موارد به عنوان فراخوانی‌های بازگشتی به فایل اجرایی perf در دسترس هستند (به پایین مراجعه کنید)\&.
.sp
به عنوان مثال، دستور \fIperf record\fR زیر می‌تواند برای ضبط تمام رویدادهای sched_wakeup در سیستم استفاده شود:
.sp
.if n \{\
.RS 4
.\}
.nf
# perf record \-a \-e sched:sched_wakeup
.fi
.if n \{\
.RE
.\}
.sp
ردگیری‌هایی که قرار است با استفاده از یک اسکریپت پردازش شوند، باید با گزینه بالا ضبط شوند: \-a برای فعال‌سازی جمع‌آوری داده در سطح کل سیستم\&.
.sp
فایل قالب برای رویداد sched_wakeup فیلدهای زیر را تعریف می‌کند (مسیر /sys/kernel/tracing/events/sched/sched_wakeup/format را ببینید):
.sp
.if n \{\
.RS 4
.\}
.nf

\&.ft C
 format:
        field:unsigned short common_type;
        field:unsigned char common_flags;
        field:unsigned char common_preempt_count;
        field:int common_pid;

        field:char comm[TASK_COMM_LEN];
        field:pid_t pid;
        field:int prio;
        field:int success;
        field:int target_cpu;
\&.ft

.fi
.if n \{\
.RE
.\}
.sp
تابع گرداننده برای این رویداد به این صورت تعریف می‌شود:
.sp
.if n \{\
.RS 4
.\}
.nf

\&.ft C
sub sched::sched_wakeup
{
   my ($event_name, $context, $common_cpu, $common_secs,
       $common_nsecs, $common_pid, $common_comm,
       $comm, $pid, $prio, $success, $target_cpu) = @_;
}
\&.ft

.fi
.if n \{\
.RE
.\}
.sp
تابع گرداننده قالب subsystem::event_name را به خود می‌گیرد\&.
.sp
آرگومان‌های $common_* در فهرست آرگومان‌های گرداننده، مجموعه‌ای از آرگومان‌ها هستند که به تمام گرداننده‌های رویداد ارسال می‌شوند؛ برخی از فیلدها با فیلدهای common_* در فایل قالب مطابقت دارند، اما برخی دیگر به صورت ساختگی تولید می‌شوند، و برخی از فیلدهای common_* نیز آن‌قدر عمومی نیستند که به عنوان آرگومان به هر رویدادی ارسال شوند اما به عنوان توابع کتابخانه‌ای در دسترس هستند\&.
.sp
در اینجا شرح مختصری از هر یک از آرگومان‌های نامتغیر رویداد آمده است:
.sp
.if n \{\
.RS 4
.\}
.nf
$event_name                نام رویداد به صورت متن
$context                   یک کوکی مات (\*(Aqcookie\*(Aq) مورد استفاده در فراخوانی‌های بازگشتی به perf
$common_cpu                پردازنده‌ای که رویداد روی آن رخ داده است
$common_secs               بخش ثانیه برچسب زمانی رویداد
$common_nsecs              بخش نانوثانیه برچسب زمانی رویداد
$common_pid                شناسه پردازه (PID) وظیفه جاری
$common_comm               نام پردازش جاری
.fi
.if n \{\
.RE
.\}
.sp
تمام فیلدهای باقی‌مانده در فایل قالب رویداد، همتایانی با همان نام به عنوان آرگومان‌های تابع گرداننده دارند، همان‌طور که در مثال بالا مشاهده می‌شود\&.
.sp
موارد فوق اصول اولیه مورد نیاز برای دسترسی مستقیم به تک‌تک فیلدهای هر رویداد در یک ردگیری را فراهم می‌کند، که ۹۰٪ آنچه را که برای نوشتن یک اسکریپت ردگیری کاربردی نیاز دارید پوشش می‌دهد\&. بخش‌های زیر بقیه موارد را پوشش می‌دهند\&.
.SH "ساختار اسکریپت (SCRIPT LAYOUT)"
.sp
هر اسکریپت Perl برای perf script باید با تنظیم مسیر جستجوی ماژول‌های Perl و بارگذاری (\*(Aquse\*(Aq کردن) چند ماژول پشتیبانی آغاز شود (توضیحات ماژول‌ها را در زیر ببینید):
.sp
.if n \{\
.RS 4
.\}
.nf

\&.ft C
 use lib "$ENV{\*(AqPERF_EXEC_PATH\*(Aq}/scripts/perl/Perf\-Trace\-Util/lib";
 use lib "\&./Perf\-Trace\-Util/lib";
 use Perf::Trace::Core;
 use Perf::Trace::Context;
 use Perf::Trace::Util;
\&.ft

.fi
.if n \{\
.RE
.\}
.sp
باقی اسکریپت می‌تواند شامل توابع گرداننده و توابع پشتیبان با هر ترتیبی باشد\&.
.sp
به جز توابع گرداننده رویداد که در بالا بررسی شد، هر اسکریپت می‌تواند مجموعه‌ای از توابع اختیاری را پیاده‌سازی کند:
.sp
تابع \fBtrace_begin\fR، در صورت تعریف، قبل از پردازش هر رویدادی فراخوانی می‌شود و به اسکریپت‌ها این فرصت را می‌دهد که وظایف راه‌اندازی اولیه را انجام دهند:
.sp
.if n \{\
.RS 4
.\}
.nf

\&.ft C
 sub trace_begin
 {
 }
\&.ft

.fi
.if n \{\
.RE
.\}
.sp
تابع \fBtrace_end\fR، در صورت تعریف، پس از پردازش تمام رویدادها فراخوانی می‌شود و به اسکریپت‌ها امکان می‌دهد کارهای پایانی اسکریپت، مانند نمایش نتایج را انجام دهند:
.sp
.if n \{\
.RS 4
.\}
.nf

\&.ft C
sub trace_end
{
}
\&.ft

.fi
.if n \{\
.RE
.\}
.sp
تابع \fBtrace_unhandled\fR، در صورت تعریف، برای هر رویدادی که گرداننده‌ای به طور صریح برای آن تعریف نشده باشد فراخوانی می‌شود\&. مجموعه استاندارد آرگومان‌های مشترک به آن ارسال می‌شود:
.sp
.if n \{\
.RS 4
.\}
.nf

\&.ft C
sub trace_unhandled
{
    my ($event_name, $context, $common_cpu, $common_secs,
        $common_nsecs, $common_pid, $common_comm) = @_;
}
\&.ft

.fi
.if n \{\
.RE
.\}
.sp
بخش‌های باقی‌مانده توضیحاتی درباره هر یک از ماژول‌های درون‌ساخت Perl در perf script و توابع مرتبط با آن‌ها ارائه می‌دهند\&.
.SH "ماژول‌ها و توابع موجود (AVAILABLE MODULES AND FUNCTIONS)"
.sp
بخش‌های زیر توابع و متغیرهای موجود از طریق ماژول‌های مختلف Perl یعنی Perf::Trace::* را شرح می‌دهند\&. برای استفاده از توابع و متغیرهای یک ماژول داده‌شده، خط متناظر \fIuse Perf::Trace::XXX\fR را به اسکریپت perf script خود اضافه کنید\&.
.SS "ماژول Perf::Trace::Core"
.sp
این توابع برخی قابلیت‌های اساسی را برای اسکریپت‌های کاربر فراهم می‌کنند\&.
.sp
توابع \fBflag_str\fR و \fBsymbol_str\fR رشته‌های خوانا برای انسان را برای فیلدهای پرچم و نمادین فراهم می‌کنند\&. این موارد متناظر با رشته‌ها و مقادیر تجزیه‌شده از فیلدهای \fIprint fmt\fR در فایل‌های قالب رویداد هستند:
.sp
.if n \{\
.RS 4
.\}
.nf
flag_str($event_name, $field_name, $field_value) \- مقدار رشته‌ای متناظر با $field_value را برای فیلد پرچم $field_name از رویداد $event_name برمی‌گرداند
symbol_str($event_name, $field_name, $field_value) \- مقدار رشته‌ای متناظر با $field_value را برای فیلد نمادین $field_name از رویداد $event_name برمی‌گرداند
.fi
.if n \{\
.RE
.\}
.SS "ماژول Perf::Trace::Context"
.sp
برخی از فیلدهای \fIcommon\fR در فایل قالب رویداد چندان هم پرکاربرد نیستند، اما با این وجود باید برای اسکریپت‌های کاربر قابل دسترس باشند\&.
.sp
ماژول Perf::Trace::Context مجموعه‌ای از توابع را تعریف می‌کند که می‌توانند برای دسترسی به این داده‌ها در زمینه رویداد جاری استفاده شوند\&. هر یک از این توابع یک متغیر $context دریافت می‌کنند، که همان متغیر $context ارسال‌شده به عنوان آرگومان دوم به هر گرداننده رویداد است\&.
.sp
.if n \{\
.RS 4
.\}
.nf
common_pc($context) \- مقدار common_preempt count را برای رویداد جاری برمی‌گرداند
common_flags($context) \- مقدار common_flags را برای رویداد جاری برمی‌گرداند
common_lock_depth($context) \- مقدار common_lock_depth را برای رویداد جاری برمی‌گرداند
.fi
.if n \{\
.RE
.\}
.SS "ماژول Perf::Trace::Util"
.sp
توابع کاربردی گوناگون برای استفاده با perf script:
.sp
.if n \{\
.RS 4
.\}
.nf
nsecs($secs, $nsecs) \- مجموع کل nsecs را بر اساس جفت secs/nsecs برمی‌گرداند
nsecs_secs($nsecs) \- بخش ثانیه کامل را با دریافت nsecs برمی‌گرداند
nsecs_nsecs($nsecs) \- باقیمانده nsecs را با دریافت nsecs برمی‌گرداند
nsecs_str($nsecs) \- رشته قابل چاپ در قالب secs\&.nsecs را برمی‌گرداند
avg($total, $n) \- میانگین را بر اساس یک مجموع و تعداد کل مقادیر برمی‌گرداند
.fi
.if n \{\
.RE
.\}
.SH "همچنین ببینید (SEE ALSO)"
.sp
\fBperf-script\fR(1)