.\" Copyright 2026 Red Hat Inc.
.\" Fri 2026-Apr 10 Serhei Makarov <serhei@serhei.io>
.\" Contact elfutils-devel@sourceware.org to correct errors or typos

.de SAMPLE
.br
.RS 0
.nf
.nh
..
.de ESAMPLE
.hy
.fi
.RE
..

.TH EU-STACKPROF 1 "2026-Apr-10" "elfutils"
.SH "نام (NAME)"
eu-stackprof \- پروفایلینگ پشته پشتهای و ردیابی ردپای اجرای برنامهها

.SH "خلاصه دستور (SYNOPSIS)"
.B eu-stackprof \fR[\fB\-v\fR|\fB\-vv\fR|...] [\fB\-\-gmon\fR] [\fB\-o\fR \fB\fIDEST\fR] [\fB\fIOPTION\fR]... [\-\- \fICMD\fR...]

.SH "توضیحات (DESCRIPTION)"

\fBeu-stackprof\fR داده‌های پروفایلینگ پشته را از perf_events لینوکس جمع‌آوری می‌کند،
چه در سراسر سیستم در میان تمامی فرایندها یا به‌صورت هدفمند برای یک
فرایند خاص (یک PID موجود از طریق \fB\-p\fR یا فرایند تازه‌راه‌اندازی‌شده از طریق آرگومان‌های
خط فرمان ارائه‌شده) و تمام فرایندهای فرزندی که از آن مشتق می‌شوند. برای دسترسی به رابط
perf_events، چه به‌صورت سراسری و چه برای یک فرایند هدفمند خاص، مجوزهای مناسب
مورد نیاز است؛ برای خلاصه‌ای از نیازمندی‌های مجوز به بخش «Arguments» در
\fIperf\_event\_open\fR(2) مراجعه کنید.

هنگامی که از گزینه \fB\-\-gmon\fR استفاده می‌شود، نتایج در قالب پرونده‌های
\fBgmon.out\fR با فرمت \fIgprof\fR\|(1) ذخیره می‌شوند. این پرونده‌ها برای
جمع‌آوری آمار با profiledb کاربرد دارند.

هنگامی که از گزینه \fB\-\-gmon\fR استفاده نمی‌شود، \fBeu-stackprof\fR آمار
پایه درباره داده‌های پروفایلینگ را جمع‌آوری کرده و در خطای استاندارد چاپ می‌کند.

.SH "گزینهها (OPTIONS)"

.TP
\fB\-e\fR \fIEVENT\fR, \fB\-\-event\fR=\fIEVENT\fR
پیکربندی نمونه‌برداری perf_events بر اساس مشخصات رویداد libpfm ارائه‌شده (برای نمونه \fBperf::CPU\-CLOCK:freq=1000\fR).

.TP
\fB\-\-event\-list\fR
فهرست کردن رویدادهای موجود libpfm و خروج.

.TP
\fB\-f, \-\-force\fR
اگر پوشه خروجی برای \fB\-\-gmon\fR از قبل حاوی پرونده‌هایی باشد که با build-idهای مشاهده‌شده شناسایی می‌شوند، آن‌ها را با داده‌های تازه جمع‌آوری‌شده بازنویسی می‌کند.

.TP
\fB\-g, \-\-gmon\fR
خروجی دادن هیستوگرام‌های شمارنده برنامه و نمودارهای فراخوانی برای هر شیء اجرایی باینری مشاهده‌شده در طول پروفایلینگ در قالب \fBgmon.out\fR متعلق به \fIgprof\fR\|(1).

.TP
\fB\-G\fR \fIMETHOD\fR, \fB\-\-hist\-split\fR=\fIMETHOD\fR
تعیین روش مورد استفاده برای تقسیم فضای آدرس به هیستوگرام‌ها برای خروجی \fB\-\-gmon\fR. مقدار METHOD باید یکی از موارد زیر باشد:
.RS
.TP
\fBnone\fR
تقسیم نکردن: نوشتن یک هیستوگرام که کل محدوده آدرس را پوشش می‌دهد.
.TP
\fBeven\fR (پیشفرض)
تقسیم فضای آدرس به هیستوگرام‌هایی با اندازه برابر جهت برآورده کردن بررسی سازگاری مقیاس در \fIgprof\fR\|(1).
.TP
\fBflex\fR
تقسیم فضای آدرس به هیستوگرام‌هایی با اندازه متغیر برای به حداقل رساندن نیازهای ذخیره‌سازی؛ نتیجه به احتمال زیاد توسط ابزار \fIgprof\fR\|(1) که نیازمند مقیاس یکدست برای تمام هیستوگرام‌ها است رد خواهد شد، اما همچنان برای profiledb مناسب خواهد بود.
.RE

.TP
\fB\-?, \-\-help\fR
چاپ فهرست کوتاهی از گزینه‌ها.

.TP
\fB\-n\fR \fIMAXFRAMES\fR, \fB\-\-maxframes\fR=\fIMAXFRAMES\fR
حد بالایی بر روی تعداد فریم‌هایی که برای هر نمونه پشته ردگیری و بازگشایی می‌شوند. در صورت فعال بودن \fB\-\-gmon\fR مقدار پیشفرض 1 است، زیرا فریم‌های بیشتر فراتر از فریم نخست برای تولید هیستوگرام gprof و داده‌های یال نمودار فراخوانی نیاز نیستند؛ در غیر این صورت مقدار پیشفرض 256 است.

.TP
\fB\-o\fR \fIDEST\fR, \fB\-\-output\fR=\fIDEST\fR
پوشه‌ای که هنگام فعال بودن خروجی \fB\-\-gmon\fR نتایج در آن نوشته می‌شوند. پیشفرض، دایرکتوری جاری است.

.TP
\fB\-p\fR \fIPID\fR, \fB\-\-pid\fR=\fIPID\fR
محدود کردن پروفایلینگ به فرایند \fIPID\fR و فرزندان آتی آن.

.TP
\fB\-v, \-\-verbose\fR
خروجی دادن اطلاعات بیشتر. می‌تواند یک یا چند بار برای افزایش سطح جزئیات مشخص شود، با ثبت هر باینری جدید، هر نمونه پشته، یا هر فریم.

.TP
\fB\-V, \-\-version\fR
چاپ نسخه برنامه.

.SH "قالب خروجی (OUTPUT FORMAT)"

هنگامی که خروجی \fB\-\-gmon\fR فعال باشد، \fBeu-stackprof\fR پرونده‌های زیر را برای هر شیء اجرایی مشاهده‌شده در میان فرایندهای پروفایل‌شده، که با build-id شناسایی می‌شوند، تولید می‌کند:

.TP
\fBgmon.BUILDID.exe\fR

پیوند نمادین (symlink) به شیء اجرایی مشاهده‌شده توسط ابزار پروفایلینگ.

.TP
\fBgmon.BUILDID.out\fR

شامل یک هیستوگرام از شمارنده‌های برنامه و یک جدول از یال‌های نمودار فراخوانی (مشاهده‌شده از ۲ فریم بالایی ردگیری پشته). با همان قالبی که توسط زیرساخت gprof تولید شده و توسط \fIgprof\fR\|(1) خوانده می‌شود.

.TP
\fBgmon.BUILDID.json\fR

متاداده در قالب JSON، شامل مسیر شیء اجرایی و اطلاعات رویداد libpfm.

.SH "مثال‌ها (EXAMPLES)"

پروفایلینگ در سراسر سیستم؛ نوشتن پرونده‌های gmon.out در پوشه جاری:
.SAMPLE
sudo eu-stackprof --gmon
.ESAMPLE

پروفایلینگ PID 1211 و فرزندان منشعب‌شده از آن؛ ثبت یک خط به ازای هر نمونه پشته؛ نوشتن پرونده‌های gmon.out در پوشه results/ و جایگزینی پرونده‌های موجود با همان build-id:
.SAMPLE
sudo eu-stackprof -vv --gmon -o results/ -p 1211 --force
.ESAMPLE

به همین ترتیب، اجرای \fBvim\fR و پروفایلینگ آن:
.SAMPLE
sudo eu-stackprof --gmon -o results/ --force -- vim test.txt
.ESAMPLE

پروفایلینگ در سراسر سیستم؛ ثبت یک خط به ازای هر فریم پشته:
.SAMPLE
sudo eu-stackprof -vvv
.ESAMPLE

.SH "گزارش باگ‌ها (REPORTING BUGS)"
گزارش اشکالات به <elfutils-devel@sourceware.org> یا
<https://sourceware.org/bugzilla>.

.SH "همچنین ببینید (SEE ALSO)"
.BR gprof (1),
.BR perf_event_open (2)