.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Required to disable full justification in groff 1.23.0. .if n .ds AD l .\" ======================================================================== .\" .IX Title "GPROFNG-COLLECT-APP 1" .TH GPROFNG-COLLECT-APP 1 2026-08-11 binutils-2.47 "User Commands" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "نام (NAME)" gprofng\-collect\-app \- جمع‌آوری داده‌های کارایی برای برنامه کاربردی هدف .SH "خلاصه دستور (SYNOPSIS)" .IX Header "خلاصه دستور (SYNOPSIS)" \&\fBgprofng collect app\fR [\fIoption(s)\fR] \fItarget\fR [\fItarget\-option(s)\fR] .SH "توضیحات (DESCRIPTION)" .IX Header "توضیحات (DESCRIPTION)" داده‌های کارایی (Performance) را در برنامه هدف جمع‌آوری می‌کند. علاوه بر نمونه‌برداری از شمارنده برنامه (PC یا Program Counter)، شمارنده‌های رویدادهای سخت‌افزاری و گزینه‌های گوناگون ردگیری (Tracing) نیز پشتیبانی می‌شوند. .PP برای نمونه، دستور زیر داده‌های کارایی را برای یک فایل اجرایی به نام \&\fBa.out\fR جمع‌آوری کرده و داده‌های ثبت‌شده را در یک پوشه آزمایش با نام \fBexample.er\fR ذخیره می‌کند. .PP .Vb 1 \& $ gprofng collect app \-o example.er ./a.out .Ve .SH "گزینه‌ها (OPTIONS)" .IX Header "گزینه‌ها (OPTIONS)" .IP \fB\-\-version\fR 4 .IX Item "--version" چاپ شماره نسخه و خروج. .IP \fB\-\-help\fR 4 .IX Item "--help" چاپ اطلاعات نحوه استفاده و خروج. .IP "\fB\-v, \-\-verbose\fR" 4 .IX Item "-v, --verbose" به‌طور پیش‌فرض، حالت پرگویی (Verbose) غیرفعال است. این گزینه آن را فعال می‌کند. .IP "\fB\-p {off | on | lo[w] | hi[gh] |\fR \fI\fR\fB}\fR" 4 .IX Item "-p {off | on | lo[w] | hi[gh] | }" غیرفعال‌سازی (\fBoff\fR) یا فعال‌سازی (\fBon\fR) پروفایل‌بندی ساعت (Clock profiling) با استفاده از دانه‌بندی پیش‌فرض نمونه‌برداری، یا فعال‌سازی ضمنی پروفایل‌بندی ساعت از طریق تعیین دانه‌بندی نمونه‌برداری (\fBlo[w]\fR، \fBhi[gh]\fR یا مقداری مشخص به میلی‌ثانیه). به‌طور پیش‌فرض، پروفایل‌بندی ساعت فعال است (\fB\-p on\fR). .IP "\fB\-h\fR \fI[,]\fR" 4 .IX Item "-h [,]" فعال‌سازی پروفایل‌بندی شمارنده‌های رویداد سخت‌افزاری و انتخاب یک یا چند شمارنده. برای مشاهده شمارنده‌های پشتیبانی‌شده در این سیستم، گزینه .B \-h را بدون آرگومان‌های دیگر به کار ببرید. .IP "\fB\-o\fR \fI\fR" 4 .IX Item "-o " تعیین نام برای پوشه آزمایش. نام باید با \&\fB.er\fR خاتمه یابد و می‌تواند شامل یک مسیر مطلق باشد (مانند \fI/tmp/experiment.er\fR). اگر آزمایشی از قبل با همین نام وجود داشته باشد، بازنویسی نخواهد شد. .IP "\fB\-O\fR \fI\fR" 4 .IX Item "-O " مشابه گزینه .B \-o است، اما بر خلاف آن، در صورت وجود پوشه آزمایشی با همین نام، آن را بدون اخطار بازنویسی می‌کند. .IP "\fB\-C\fR \fI\fR" 4 .IX Item "-C " افزودن حداکثر ۱۰ رشته یادداشت (کامنت) به آزمایش. این یادداشت‌ها در بخش نکات هدر ظاهر می‌شوند و با دستور \&\fBgprofng display text\fR با استفاده از گزینه .B \-header قابل بازیابی هستند. .IP "\fB\-j {on | off |\fR \fI\fR\fB}\fR" 4 .IX Item "-j {on | off | }" کنترل پروفایل‌بندی جاوا هنگامی که هدف یک ماشین JVM است. مقادیر مجاز برای این گزینه عبارتند از: .RS 4 .IP \fBon\fR 4 .IX Item "on" ثبت داده‌های پروفایل‌بندی برای ماشین JVM و شناسایی متدهای کامپایل‌شده توسط ماشین مجازی Java HotSpot. همچنین پشته‌های فراخوانی جاوا را نیز ثبت می‌کند. .IP \fBoff\fR 4 .IX Item "off" داده‌های پروفایل‌بندی جاوا ثبت نشوند. داده‌های پروفایل‌بندی برای پشته‌های فراخوانی بومی (Native) همچنان ثبت می‌شوند. .IP \fI\fR 4 .IX Item "" ثبت داده‌های پروفایل‌بندی برای JVM، و استفاده از JVM نصب‌شده در \&\fI\fR. .RE .RS 4 .Sp حالت پیش‌فرض \fB\-j on\fR است. .RE .IP "\fB\-J\fR \fI\fR" 4 .IX Item "-J " مشخص‌کردن یک یا چند گزینه اضافی برای ارسال به JVM مورد استفاده. اگر فهرست \&\fIjvm\-option(s)\fR شامل بیش از یک گزینه باشد، باید درون علامت نقل‌قول (کوتیشن) قرار گیرد. موارد موجود در فهرست باید با فاصله یا تب از یکدیگر جدا شوند. هر مورد به عنوان یک گزینه جداگانه به JVM ارسال می‌شود. توجه داشته باشید که این گزینه به طور ضمنی \fB\-j on\fR را فعال می‌کند. .IP "\fB\-t\fR \fI\fR\fB[m|s]\fR" 4 .IX Item "-t [m|s]" گردآوری داده‌ها برای مدت زمان مشخص‌شده. مدت زمان می‌تواند یک عدد تکی باشد که به صورت اختیاری پس از آن \fBm\fR برای تعیین دقیقه یا \fBs\fR برای تعیین ثانیه (حالت پیش‌فرض) قرار می‌گیرد. .Sp مدت زمان می‌تواند شامل دو عدد نیز باشد که با علامت خط تیره (\-) از یکدیگر جدا شده‌اند. اگر یک عدد تکی داده شود، داده‌ها از آغاز اجرا تا زمان مشخص‌شده گردآوری می‌شوند. اگر دو عدد مشخص شود، داده‌ها از زمان نخست تا زمان دوم گردآوری می‌شوند. در صورتی که زمان دوم صفر باشد، داده‌ها تا پایان اجرای برنامه جمع‌آوری می‌شوند. اگر دو عدد غیرصفر مشخص شوند، عدد اول باید از عدد دوم کوچکتر باشد. .IP \fB\-n\fR 4 .IX Item "-n" برای اجرای آزمایشی (Dry run) به کار می‌رود. چندین تنظیم زمان اجرا نمایش داده می‌شوند، اما برنامه هدف اجرا نمی‌شود و هیچ داده کارایی جمع‌آوری نخواهد شد. .IP "\fB\-F {off|on|=\fR\fIregex\fR\fB}\fR" 4 .IX Item "-F {off|on|=regex}" کنترل اینکه آیا داده‌های فرآیندهای فرزند (نواده) ثبت شوند یا خیر. برای غیرفعال/فعال‌سازی این ویژگی از \fBoff\fR/\fBon\fR استفاده کنید. از \&\fB=\fR\fIregex\fR برای ثبت داده‌های فرآیندهایی استفاده کنید که نام فایل اجرایی آن‌ها با عبارت باقاعده مطابقت دارد. تنها نام پایه (Basename) فایل اجرایی بررسی می‌شود، نه مسیر کامل آن. اگر از فاصله‌ها یا نویسه‌هایی استفاده می‌شود که توسط پوسته (Shell) تفسیر می‌شوند، عبارت \fIregex\fR را داخل علامت نقل‌قول تکی (Single quotes) قرار دهید. حالت پیش‌فرض \fB\-F on\fR است. .IP "\fB\-a {off|on|ldobjects|src|usedldobjects|usedsrc}\fR" 4 .IX Item "-a {off|on|ldobjects|src|usedldobjects|usedsrc}" تعیین نحوه بایگانی فایل‌های باینری و سایر فایل‌ها. علاوه بر غیرفعال‌سازی این ویژگی (\fBoff\fR) یا فعال‌سازی بایگانی همه اشیاء بارگذاری و سورس‌ها (\fBon\fR)، سایر گزینه‌ها امکان انتخاب دقیق‌تری را فراهم می‌کنند. .Sp تمامی این گزینه‌ها بایگانی را فعال می‌کنند، اما کلیدواژه مشخص می‌کند که دقیقاً چه مواردی انتخاب شوند: تمام اشیاء بارگذاری (ldobjects)، تمام فایل‌های منبع (src)، اشیاء بارگذاری مرتبط با شمارنده برنامه (usedldobjects)، یا فایل‌های منبع مرتبط با شمارنده برنامه (usedsrc). حالت پیش‌فرض \fB\-a ldobjects\fR است. .IP "\fB\-S {off|on|\fR\fI\fR\fB}\fR" 4 .IX Item "-S {off|on|}" غیرفعال‌سازی (off) یا فعال‌سازی (on) نمونه‌برداری دوره‌ای از مصرف منابع در سطح کل فرآیند. به‌طور پیش‌فرض، نمونه‌برداری در هر ثانیه رخ می‌دهد. برای تغییر این بازه از شناسه \&\fI\fR استفاده کنید. حالت پیش‌فرض \fB\-S on\fR است. .IP "\fB\-y\fR \fI\fR\fB[,r]\fR" 4 .IX Item "-y [,r]" کنترل ثبت داده‌ها با سیگنالی با نام \fI\fR که با عنوان سیگنال توقف-ازسرگیری (Pause-resume signal) شناخته می‌شود. هر زمان که سیگنال داده‌شده به فرآیند تحویل داده شود، وضعیت میان متوقف (هیچ داده‌ای ثبت نمی‌شود) و ازسرگرفته‌شده (داده‌ها ثبت می‌شوند) جابه‌جا می‌شود. .Sp به‌طور پیش‌فرض، جمع‌آوری داده‌ها در وضعیت متوقف آغاز می‌شود. اگر شناسه اختیاری \&\fBr\fR مشخص شود، جمع‌آوری داده‌ها در وضعیت ازسرگرفته‌شده آغاز شده و بلافاصله فرآیند گردآوری شروع می‌شود. .Sp سیگنال‌های SIGUSR1 یا SIGUSR2 برای این منظور توصیه می‌شوند، اما هر سیگنالی که توسط برنامه هدف استفاده نشده باشد می‌تواند به کار رود. .IP "\fB\-l\fR \fI\fR" 4 .IX Item "-l " تعیین سیگنالی که ثبت یک نمونه از مصرف منابع در سطح کل فرآیند را آغاز می‌کند. هنگامی که سیگنال \fI\fR به فرآیند تحویل داده شود، یک نمونه ثبت می‌گردد. .Sp سیگنال را می‌توان با نام کامل، بدون حروف ابتدایی \f(CW\*(C`SIG\*(C'\fR یا با شماره سیگنال مشخص کرد. توجه داشته باشید که برای ارسال سیگنال می‌توان از دستور \fBkill\fR استفاده کرد. .Sp اگر از هر دو گزینه .B \-l و .B \-y استفاده شود، سیگنال‌ها باید متفاوت باشند. .IP "\fB\-s\fR \fI