.\" -*- 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 "GCOV-TOOL 1"
.TH GCOV-TOOL 1 2026-08-10 gcc-16.2.1 GNU
.\" 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)"
gcov\-tool \- ابزار پردازش آفلاین پروفایل gcda
.SH "خلاصه دستور (SYNOPSIS)"
.IX Header "SYNOPSIS"
gcov\-tool [\fB\-v\fR|\fB\-\-version\fR] [\fB\-h\fR|\fB\-\-help\fR]
.PP
gcov\-tool merge [merge\-options] \fIdirectory1\fR \fIdirectory2\fR
     [\fB\-o\fR|\fB\-\-output\fR \fIdirectory\fR]
     [\fB\-v\fR|\fB\-\-verbose\fR]
     [\fB\-w\fR|\fB\-\-weight\fR \fIw1,w2\fR]
.PP
gcov\-tool merge\-stream [merge\-stream\-options] [\fIfile\fR]
     [\fB\-v\fR|\fB\-\-verbose\fR]
     [\fB\-w\fR|\fB\-\-weight\fR \fIw1,w2\fR]
.PP
gcov\-tool rewrite [rewrite\-options] \fIdirectory\fR
     [\fB\-n\fR|\fB\-\-normalize\fR \fIlong_long_value\fR]
     [\fB\-o\fR|\fB\-\-output\fR \fIdirectory\fR]
     [\fB\-s\fR|\fB\-\-scale\fR \fIfloat_or_simple\-frac_value\fR]
     [\fB\-v\fR|\fB\-\-verbose\fR]
.PP
gcov\-tool overlap [overlap\-options] \fIdirectory1\fR \fIdirectory2\fR
     [\fB\-f\fR|\fB\-\-function\fR]
     [\fB\-F\fR|\fB\-\-fullname\fR]
     [\fB\-h\fR|\fB\-\-hotonly\fR]
     [\fB\-o\fR|\fB\-\-object\fR]
     [\fB\-t\fR|\fB\-\-hot_threshold\fR] \fIfloat\fR
     [\fB\-v\fR|\fB\-\-verbose\fR].SH "توضیحات (DESCRIPTION)"
.IX Header "DESCRIPTION"
ابزار \&\fBgcov\-tool\fR یک ابزار آفلاین برای پردازش فایل‌های پروفایل gcda مربوط به gcc است.
.PP
در حال حاضر gcov\-tool از قابلیت‌های زیر پشتیبانی می‌کند:
.IP * 4
ادغام دو مجموعه پروفایل به همراه وزن‌ها.
.IP * 4
خواندن جریانی از پروفایل‌ها به همراه نام‌های فایل مرتبط و ادغام آن با مجموعه‌ای از پروفایل‌ها با وزن‌ها.
.IP * 4
خواندن یک مجموعه پروفایل و بازنویسی محتویات پروفایل. می‌توان مقادیر شمارنده‌ها را مقیاس‌بندی یا نرمال‌سازی کرد.
.PP
نمونه‌هایی از موارد کاربرد این ابزار عبارتند از:
.IP * 4
جمع‌آوری پروفایل‌ها برای مجموعه‌های متفاوتی از ورودی‌ها و استفاده از این ابزار برای ادغام آن‌ها. می‌توان با تعیین وزن، اهمیت نسبی هر ورودی را لحاظ کرد.
.IP * 4
جمع‌آوری پروفایل‌ها از سیستم‌های مقصد فاقد سیستم فایل (محیط‌های freestanding). ادغام پروفایل‌های جمع‌آوری‌شده با پروفایل‌های مرتبط موجود روی سیستم میزبان. می‌توان با تعیین وزن، اهمیت نسبی هر ورودی را لحاظ کرد.
.IP * 4
بازنویسی پروفایل پس از حذف زیرمجموعه‌ای از فایل‌های gcda، ضمن حفظ سازگاری خلاصه (summary) و هیستوگرام (histogram).
.IP * 4
همچنین می‌توان از آن برای اشکال‌زدایی کد libgcov استفاده کرد، زیرا این ابزار بخش عمده کد خود را با کتابخانه زمان اجرا به اشتراک می‌گذارد.
.PP
توجه داشته باشید که برای عملیات ادغام، این پروفایل تولیدشده به‌صورت آفلاین ممکن است مقادیری کمی متفاوت از پروفایل ادغام‌شده به‌صورت آنلاین داشته باشد. در اینجا فهرستی از تفاوت‌های معمول آورده شده است:
.IP * 4
تفاوت هیستوگرام: این ابزار آفلاین پس از ادغام شمارنده‌ها، هیستوگرام را مجدداً محاسبه می‌کند. بنابراین، هیستوگرام حاصل دقیق است. ادغام آنلاین این قابلیت را ندارد \-\- هیستوگرام از دو هیستوگرام ادغام می‌شود و نتیجه یک تقریب است.
.IP * 4
تفاوت چک‌سام خلاصه: چک‌سام خلاصه از یک عملیات CRC32 استفاده می‌کند. این مقدار به ترتیب لیست پیوندی اشیاء gcov\-info بستگی دارد. این ترتیب در gcov\-tool با ادغام آنلاین متفاوت است. انتظار می‌رود که چک‌سام‌های خلاصه متفاوت باشند. این موضوع اهمیت چندانی ندارد زیرا کامپایلر از این چک‌سام در هیچ‌کجا استفاده نمی‌کند.
.IP * 4
تفاوت مقادیر شمارنده پروفایل مقداری (value profile): برخی مقادیر شمارنده برای پروفایل مقداری به زمان اجرا وابسته‌اند، مانند آدرس‌های heap. مشاهده مقداری تفاوت در این‌گونه شمارنده‌ها طبیعی است.
.SH "گزینه‌ها (OPTIONS)"
.IX Header "OPTIONS"
.IP \fB\-h\fR 4
.IX Item "-h"
.PD 0
.IP \fB\-\-help\fR 4
.IX Item "--help"
.PD
نمایش راهنمای استفاده از \fBgcov\-tool\fR (روی خروجی استاندارد) و خروج بدون انجام هیچ پردازش دیگری.
.IP \fB\-v\fR 4
.IX Item "-v"
.PD 0
.IP \fB\-\-version\fR 4
.IX Item "--version"
.PD
نمایش شماره نسخه \fBgcov\-tool\fR (روی خروجی استاندارد) و خروج بدون انجام هیچ پردازش دیگری.
.IP \fBmerge\fR 4
.IX Item "merge"
ادغام دو دایرکتوری پروفایل.
.RS 4
.IP "\fB\-o\fR \fIdirectory\fR" 4
.IX Item "-o directory"
.PD 0
.IP "\fB\-\-output\fR \fIdirectory\fR" 4
.IX Item "--output directory"
.PD
تعیین دایرکتوری پروفایل خروجی. نام پیش‌فرض دایرکتوری خروجی \&\fImerged_profile\fR است.
.IP \fB\-v\fR 4
.IX Item "-v"
.PD 0
.IP \fB\-\-verbose\fR 4
.IX Item "--verbose"
.PD
فعال‌سازی حالت پرگو.
.IP "\fB\-w\fR \fIw1\fR\fB,\fR\fIw2\fR" 4
.IX Item "-w w1,w2"
.PD 0
.IP "\fB\-\-weight\fR \fIw1\fR\fB,\fR\fIw2\fR" 4
.IX Item "--weight w1,w2"
.PD
تنظیم وزن‌های ادغام به ترتیب برای \fIdirectory1\fR و \fIdirectory2\fR. وزن پیش‌فرض برای هر دو 1 است.
.RE
.RS 4
.RE
.IP \fBmerge\-stream\fR 4
.IX Item "merge-stream"
جمع‌آوری پروفایل‌ها به همراه نام‌های فایل مرتبط از یک جریان داده‌ای \fIgcfn\fR و \fIgcda\fR. خواندن جریان از فایل مشخص‌شده توسط \fIfile\fR یا از \&\fIstdin\fR. ادغام پروفایل‌ها با پروفایل‌های مرتبط در سیستم فایل میزبان. اعمال وزن‌های اختیاری هنگام ادغام پروفایل‌ها.
.Sp
برای تولید جریان داده‌ای \fIgcfn\fR و \fIgcda\fR در سیستم مقصد، لطفاً به توابع \f(CW\*(C`_\|_gcov_filename_to_gcfn()\*(C'\fR و \&\f(CW\*(C`_\|_gcov_info_to_gcda()\*(C'\fR که در \f(CW\*(C`#include <gcov.h>\*(C'\fR تعریف شده‌اند مراجعه کنید.
.RS 4
.IP \fB\-v\fR 4
.IX Item "-v"
.PD 0
.IP \fB\-\-verbose\fR 4
.IX Item "--verbose"
.PD
فعال‌سازی حالت پرگو.
.IP "\fB\-w\fR \fIw1\fR\fB,\fR\fIw2\fR" 4
.IX Item "-w w1,w2"
.PD 0
.IP "\fB\-\-weight\fR \fIw1\fR\fB,\fR\fIw2\fR" 4
.IX Item "--weight w1,w2"
.PD
تنظیم وزن‌های ادغام به ترتیب برای پروفایل‌های حاصل از جریان داده‌ای \fIgcfn\fR و \fIgcda\fR و پروفایل‌های مرتبط در سیستم فایل میزبان. وزن پیش‌فرض برای هر دو 1 است.
.RE
.RS 4
.RE
.IP \fBrewrite\fR 4
.IX Item "rewrite"
خواندن دایرکتوری پروفایل مشخص‌شده و بازنویسی آن در یک دایرکتوری جدید.
.RS 4
.IP "\fB\-n\fR \fIlong_long_value\fR" 4
.IX Item "-n long_long_value"
.PD 0
.IP "\fB\-\-normalize <long_long_value>\fR" 4
.IX Item "--normalize <long_long_value>"
.PD
نرمال‌سازی پروفایل. مقدار مشخص‌شده، بیشینه مقدار شمارنده در پروفایل جدید خواهد بود.
.IP "\fB\-o\fR \fIdirectory\fR" 4
.IX Item "-o directory"
.PD 0
.IP "\fB\-\-output\fR \fIdirectory\fR" 4
.IX Item "--output directory"
.PD
تعیین دایرکتوری پروفایل خروجی. نام پیش‌فرض خروجی \fIrewrite_profile\fR است.
.IP "\fB\-s\fR \fIfloat_or_simple\-frac_value\fR" 4
.IX Item "-s float_or_simple-frac_value"
.PD 0
.IP "\fB\-\-scale\fR \fIfloat_or_simple\-frac_value\fR" 4
.IX Item "--scale float_or_simple-frac_value"
.PD
مقیاس‌بندی شمارنده‌های پروفایل. مقدار مشخص‌شده می‌تواند به‌صورت یک عدد ممیز شناور، یا یک کسر ساده مانند 1، 2، 2/3 و 5/3 باشد.
.IP \fB\-v\fR 4
.IX Item "-v"
.PD 0
.IP \fB\-\-verbose\fR 4
.IX Item "--verbose"
.PD
فعال‌سازی حالت پرگو.
.RE
.RS 4
.RE
.IP \fBoverlap\fR 4
.IX Item "overlap"
محاسبه امتیاز هم‌پوشانی بین دو دایرکتوری پروفایل مشخص‌شده. امتیاز هم‌پوشانی بر اساس پروفایل‌های کمان (arc) محاسبه می‌شود. این امتیاز به‌صورت مجموع min (p1_counter[i] / p1_sum_all, p2_counter[i] / p2_sum_all) برای تمام شمارنده‌های کمان i تعریف می‌شود، که در آن p1_counter[i] و p2_counter[i] دو شمارنده متناظر، و p1_sum_all و p2_sum_all به ترتیب مجموع مقادیر شمارنده‌ها در پروفایل ۱ و پروفایل ۲ هستند.
.RS 4
.IP \fB\-f\fR 4
.IX Item "-f"
.PD 0
.IP \fB\-\-function\fR 4
.IX Item "--function"
.PD
چاپ امتیاز هم‌پوشانی در سطح تابع..IP \fB\-F\fR 4
.IX Item "-F"
.PD 0
.IP \fB\-\-fullname\fR 4
.IX Item "--fullname"
.PD
چاپ نام کامل فایل gcda.
.IP \fB\-h\fR 4
.IX Item "-h"
.PD 0
.IP \fB\-\-hotonly\fR 4
.IX Item "--hotonly"
.PD
تنها چاپ اطلاعات مربوط به شیءها/توابع پرکاربرد (hot).
.IP \fB\-o\fR 4
.IX Item "-o"
.PD 0
.IP \fB\-\-object\fR 4
.IX Item "--object"
.PD
چاپ امتیاز هم‌پوشانی در سطح شیء (object).
.IP "\fB\-t\fR \fIfloat\fR" 4
.IX Item "-t float"
.PD 0
.IP "\fB\-\-hot_threshold <float>\fR" 4
.IX Item "--hot_threshold <float>"
.PD
تنظیم مقدار آستانه برای شمارندهٔ پرکاربرد (hot counter).
.IP \fB\-v\fR 4
.IX Item "-v"
.PD 0
.IP \fB\-\-verbose\fR 4
.IX Item "--verbose"
.PD
فعال‌سازی حالت پرگو (verbose).
.RE
.RS 4
.RE
.SH "همچنین ببینید (SEE ALSO)"
.IX Header "SEE ALSO"
\&\fBgpl\fR\|(7)، \fBgfdl\fR\|(7)، \fBfsf\-funding\fR\|(7)، \fBgcc\fR\|(1)، \fBgcov\fR\|(1) و مدخل Info برای
\&\fIgcc\fR.
.SH "کپی‌رایت و تکثیر (COPYRIGHT)"
.IX Header "COPYRIGHT"
کپی‌رایت (c) 2014\-2026 Free Software Foundation, Inc.
.PP
مجوز کپی، توزیع و/یا تغییر این سند تحت شرایط «مجوز مستندات آزاد گنو» (GNU Free Documentation License)، نگارش ۱٫۳ یا هر نگارش بعدی منتشرشده توسط بنیاد نرم‌افزار آزاد (Free Software Foundation) اعطا می‌شود؛ با بخش‌های تغییرناپذیر «GNU General Public License» و «Funding Free Software»، متن‌های روی جلد (a) (زیر را ببینید) و متن‌های پشت جلد (b) (زیر را ببینید). یک نسخه از این مجوز در صفحهٔ راهنمای \fBgfdl\fR\|(7) گنجانده شده است.
.PP
(a) متن روی جلد FSF عبارت است از:
.PP
.Vb 1
\&     A GNU Manual
.Ve
.PP
(b) متن پشت جلد FSF عبارت است از:
.PP
.Vb 3
\&     You have freedom to copy and modify this GNU Manual, like GNU
\&     software.  Copies published by the Free Software Foundation raise
\&     funds for GNU development.
.Ve