.TH GPROFNG-ARCHIVE 1 "2026-08-11" "binutils-2.47" "دستورات کاربر"
.nh
.SH "نام (NAME)"
gprofng-archive \- بایگانی داده‌های حاصل از پروفایل‌بندی با ابزار gprofng
.SH "خلاصه دستور (SYNOPSIS)"
.B gprofng archive
[\fIگزینه‌ها\fR] \fIexperiment\fR
.SH "توضیحات (DESCRIPTION)"
ابزار
.B gprofng archive
فایل‌های باینری و کدهای منبع برنامه‌ی هدف را درون دایرکتوری آزمایش (\fIexperiment\fR) بایگانی می‌کند تا داده‌های آزمایش مستقل و قابل‌انتقال به سیستم‌های دیگر باشند.
.PP
به‌طور پیش‌فرض، فایل‌های باینری در زمان ثبت داده‌ها ذخیره می‌شوند، اما کدهای منبع برنامه در آزمایش ذخیره نمی‌شوند. این ابزار امکان می‌دهد این رویه را تغییر دهید و بعداً فایل‌ها و مؤلفه‌های لازم را به آزمایش بیفزایید.
.PP
این دستور باید حتماً روی همان سیستمی اجرا شود که داده‌های پروفایل‌بندی روی آن ضبط شده‌اند.
.SH "گزینه‌ها (OPTIONS)"
.TP
\fB\-\-version\fR
چاپ شماره نسخه و خروج.
.TP
\fB\-\-help\fR
نمایش راهنمای استفاده و خروج.
.TP
\fB\-a {off | on | ldobjects | src | usedldobjects | used[src]}\fR
تعیین نحوه بایگانی فایل‌های باینری و سایر پرونده‌ها. علاوه بر غیرفعال‌کردن این سازوکار (\fBoff\fR) یا بایگانی همه اشیاء بارگذاری و سورس‌ها (\fBon\fR)، سایر گزینه‌ها امکان انتخاب دقیق‌تر مؤلفه‌ها را فراهم می‌کنند.
.PP
تمامی این مقادیر بایگانی را فعال می‌کنند، اما هر کلیدواژه مشخص می‌سازد دقیقاً چه مواردی انتخاب شوند: تمام اشیاء بارگذاری (\fBldobjects\fR)، تمام فایل‌های منبع (\fBsrc\fR)، اشیاء بارگذاری مرتبط با شمارنده برنامه (\fBusedldobjects\fR) یا فایل‌های منبع مرتبط با شمارنده برنامه (\fBused[src]\fR). حالت پیش‌فرض \fB\-a ldobjects\fR است.
.TP
\fB\-d\fR \fIpath\fR
مشخص‌کردن مسیر مطلق (\fIpath\fR) به یک بایگانی مشترک (\fIcommon archive\fR). بایگانی مشترک پوشه‌ای است که فایل‌های بایگانی‌شده در آن نگهداری می‌شوند. اگر این پوشه وجود نداشته باشد، به‌طور خودکار ایجاد می‌شود. فایل‌ها در پوشه بایگانی مشترک ذخیره شده و یک پیوند نمادین (Symbolic Link) به آن‌ها در بایگانی آزمایش قرار می‌گیرد.
.TP
\fB\-F\fR
اجبار در نوشتن یا بازنویسی فایل‌های \fI.archive\fR. تمام فایل‌های بایگانی‌شده قبلی حذف شده و مجدداً بازسازی می‌شوند؛ مگر اینکه از گزینه
.B \-n
یا
.B \-m
استفاده شده باشد، یا اینکه آزمایش یک زیرآزمایش باشد.
.TP
\fB\-m\fR \fIregex\fR
تنها فایل‌های منبع، اشیاء کامپایل‌شده (Object) و فایل‌های اطلاعات اشکال‌زدایی را بایگانی می‌کند که نام مسیر کامل آن‌ها با عبارت باقاعده استاندارد پازیکس (\fIregex\fR) تطابق داشته باشد.
.TP
\fB\-n\fR
فقط آزمایش نام‌برده‌شده را بایگانی می‌کند و فرآیندها یا آزمایش‌های زیرمجموعه آن را نادیده می‌گیرد.
.TP
\fB\-q\fR
جلوگیری از چاپ هشدارها در خروجی خطای استاندارد (\fIstderr\fR). هشدارها در فایل \fI.archive\fR درون دایرکتوری آزمایش ثبت می‌شوند و در خروجی دستور
.B gprofng display text
قابل مشاهده خواهند بود.
.TP
\fB\-r\fR \fIpath\fR
تعیین مکان یک بایگانی مشترک از طریق مسیر نسبی (\fIpath\fR). بایگانی مشترک پوشه‌ای حاوی فایل‌های بایگانی‌شده است و اگر وجود نداشته باشد ایجاد می‌شود. فایل‌ها در این دایرکتوری ذخیره شده و پیوندی نمادین به آن‌ها در بایگانی آزمایش ثبت می‌شود.
.TP
\fB\-s\fR \fIselection\fR
تعیین نحوه بایگانی فایل‌های منبع. مقادیر مجاز برای آرگومان \fIselection\fR عبارتند از:
.RS 4
.TP
\fBno\fR
هیچ فایل منبعی بایگانی نشود.
.TP
\fBall\fR
تمام فایل‌های منبع و اشیائی که یافت شوند بایگانی شوند.
.TP
\fBused[src]\fR
فقط فایل‌های منبع و اشیائی بایگانی شوند که برای توابع مرتبط با آن‌ها داده‌ای در آزمایش ثبت شده باشد و در دسترس باشند.
.RE
.RS 4
.PP
به‌طور پیش‌فرض، فایل‌های منبع برنامه در دایرکتوری آزمایش بایگانی نمی‌شوند. در صورت استفاده از گزینه
.B \-s all
یا
.BR \-s\ used ,
سورس‌ها و فایل‌های شیء بایگانی می‌شوند. این گزینه‌ها تضمین می‌کنند که فایل‌های منبع در آزمایش حفظ شوند؛ حتی اگر کدهای منبع اصلی تغییر کنند یا بعداً دردسترس نباشند.
.PP
چنانچه فایل‌های بایگانی پیدا نشوند، می‌توانید دستور
.B addpath
یا
.B pathmap
(یا هر دو) را در فایل
.I .er.rc
درج کنید تا مسیر فایل‌های ناموجود مشخص شود.
.RE
.SH "نکات (NOTES)"
.SS "بایگانی فایل‌های باینری برنامه"
به‌طور پیش‌فرض، فایل‌های باینری در زمان ایجاد آزمایش به‌صورت خودکار بایگانی می‌شوند. با این حال، در شرایط زیر بایگانی انجام نمی‌گیرد:
.IP \(bu 2
اگر برنامه در حال پروفایل‌بندی پیش از پایان عادی کار خود لغو یا متوقف شود.
.IP \(bu 2
اگر یک فرآیندِ در حال اجرا (Running Process) پروفایل شود.
.IP \(bu 2
اگر فرآیند بایگانی در زمان پروفایل‌بندی صراحتاً غیرفعال شده باشد؛ برای مثال با استفاده از گزینه
.B \-a off
در دستور
.BR "gprofng collect app" .
.PP
در این حالت‌ها، باید ابزار
.B gprofng archive
را به صورت دستی و الزاماً روی همان سیستمی که داده‌های آزمایش ثبت شده‌اند اجرا کنید.
.PP
بایگانی داده‌های آزمایش حین جمع‌آوری اطلاعات، به‌ویژه در برنامه‌هایی با فرآیندهای فرزند پرشمار، بار پردازشی بالایی تحمیل می‌کند. در چنین وضعیتی، راهکار کارآمدتر این است که هنگام گردآوری داده‌ها گزینه
.B \-a off
را به کار ببرید. پس از اتمام اجرای برنامه، می‌توانید با اجرای دستور همراه با گزینه
.B \-s all
داده‌ها را بایگانی کنید. این کار تمام فایل‌های اجرایی و منبع را در آزمایش ذخیره خواهد کرد.
.PP
اگر حین بایگانی خطایی مبنی بر پیدا نشدن یک فایل اجرایی یا منبع رخ داد، می‌توانید با افزودن دستور
.B addpath
به فایل
.I .er.rc
مسیر فایل‌های ناموجود را معین کنید. پس از افزودن این دستور، بایگانی آزمایش را دوباره اجرا فرمایید. این فرآیند می‌تواند به دفعات مورد نیاز تا بایگانی کامل تمام فایل‌ها تکرار شود.
.PP
عملیات بایگانی باید روی همان سیستمی انجام شود که آزمایش در آن گردآوری شده است. اگر برخی فایل‌ها (مانند فایل‌های منبع یا آبجکت) در آن سیستم در دسترس نباشند، می‌توانید ادامه بایگانی را روی سیستم دیگری که به آن فایل‌ها دسترسی دارد انجام دهید؛ برای مثال سیستمی که برنامه روی آن کامپایل و ساخته شده است.
.PP
برخی از برنامه‌های جاوا اشیاء اشتراکی را درون فایل‌های jar نگهداری می‌کنند. این اشیاء به‌طور پیش‌فرض بایگانی نمی‌شوند. برای بایگانی اشیاء درون فایل‌های jar، دستور
.B addpath
را در فایل
.I .er.rc
قرار دهید. این دستور باید مسیر فایل jar را همراه با نام خود فایل مشخص سازد. فایل
.I .er.rc
باید در پوشه خانگی کاربر یا دایرکتوری والد آزمایش ذخیره شود.
.SS "بایگانی فایل‌های منبع برنامه"
به‌طور پیش‌فرض، فایل‌های منبع برنامه در آزمایش بایگانی نمی‌شوند. با اجرای دستور
.B gprofng archive
همراه با گزینه
.B \-s all
یا
.B \-s used
روی هر آزمایش، می‌توانید کدهای منبع را در آزمایش ذخیره کنید.
.SS "بایگانی خودکار فایل‌های منبع"
با تنظیم متغیر محیطی
.B GPROFNG_ARCHIVE
می‌توانید کاری کنید که پس از اتمام آزمایش، فایل‌های منبع به‌شکل خودکار بایگانی شوند. این متغیر محیطی می‌تواند شامل آرگومان‌های
.B \-s
و
.B \-m
به‌صورت جفت‌های کلید و مقدار باشد که با یک یا چند فاصله از یکدیگر جدا شده‌اند.
.PP
اگر چند آرگومان
.B \-s
در خط فرمان مشخص شود، آخرین آرگومان اعمال خواهد شد. چنانچه
.B \-s
هم در خط فرمان وارد شود و هم در متغیر محیطی مقداردهی شده باشد، مقدار تعیین‌شده در متغیر محیطی اولویت خواهد داشت.
.PP
توجه داشته باشید که اگر بایگانی خودکار فایل‌های منبع حین گردآوری داده‌ها با استفاده از متغیر
.B GPROFNG_ARCHIVE
یا گزینه‌های
.B \-a src
و
.B \-a usedsrc
فعال شده باشد، توصیه می‌شود با اجرای دستور
.B gprofng archive \-s all
یا
.B gprofng archive \-s used
اطمینان یابید که فایل‌های منبع به‌درستی شناسایی و ذخیره شده‌اند.
.SS "سایر نکات و محدودیت‌ها"
.IP \(bu 2
گزینه‌های
.B \-d
و
.B \-r
ناسازگار با یکدیگر بوده و نمی‌توانند هم‌زمان استفاده شوند.
.IP \(bu 2
هنگام استفاده از گزینه
.B \-d
یا
.BR \-r ,
می‌توانید متغیر محیطی
.B GPROFNG_ARCHIVE_COMMON_DIR
را برای تعیین مکان بایگانی مشترک به کار ببرید. این قابلیت هنگام نوشتن اسکریپت‌های پروفایل‌بندی برنامه بسیار سودمند است.
.IP \(bu 2
اگر بیش از یک گزینه
.B \-s
در خط فرمان مشخص شود یا در متغیر محیطی تعریف گردد، مقادیر تمام آن‌ها باید یکسان باشد؛ در غیر این صورت
.B gprofng archive
با خطا متوقف می‌شود.
.IP \(bu 2
این ابزار توانایی پردازش آزمایش‌های ضبط‌شده با نسخه‌های قدیمی‌تر را ندارد. اجرای آن روی چنین آزمایش‌هایی پیام هشدار چاپ خواهد کرد. همواره از نسخه‌ای از
.B gprofng archive
استفاده کنید که آزمایش با همان نسخه ضبط شده است.
.SH "همچنین ببینید (SEE ALSO)"
.BR gprofng (1),
.BR gprofng\-collect\-app (1),
.BR gprofng\-display\-html (1),
.BR gprofng\-display\-src (1),
.BR gprofng\-display\-text (1)
.PP
راهنمای کاربری ابزار gprofng در قالب کتابچه راهنمای Texinfo نگهداری می‌شود. در صورت نصب بودن برنامه‌های
.B info
و
.BR gprofng ,
با دستور زیر می‌توانید به این مستندات دسترسی داشته باشید:
.PP
.nf
.RS 4
info gprofng
.RE
.fi
.SH "حق نشر (COPYRIGHT)"
حق نشر \(co 2022\-2026 بنیاد نرم‌افزارهای آزاد (Free Software Foundation, Inc.)
.PP
اجازه نسخه‌برداری، توزیع و/یا تغییر این سند تحت شرایط مجوز مستندات آزاد گنو (GNU Free Documentation License)، نسخه ۱.۳ یا هر نسخه جدیدتر منتشرشده توسط بنیاد نرم‌افزارهای آزاد داده می‌شود؛ بدون بخش‌های تغییرناپذیر، بدون متون روی جلد و بدون متون پشت جلد. نسخه‌ای از این مجوز در بخشی با عنوان "GNU Free Documentation License" قرار گرفته است.