.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.47)
.\"
.\" 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-04-30 gcc-16.1.0 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
تفاوت در بافت‌نگار (histogram): این ابزار برون‌خط بافت‌نگار را پس از ادغام شمارنده‌ها مجدداً محاسبه می‌کند. بنابراین بافت‌نگار حاصل دقیق است. ادغام آنلاین این قابلیت را ندارد؛ یعنی بافت‌نگار از ادغام دو بافت‌نگار حاصل می‌شود و نتیجه تقریبی است.
.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 به ترتیب مجموع مقادیر شمارنده در پروفایل 1 و پروفایل 2 هستند.
.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
تنها چاپ اطلاعات برای اشیاء یا توابع داغ (پربسامد).
.IP \fB\-o\fR 4
.IX Item "-o"
.PD 0
.IP \fB\-\-object\fR 4
.IX Item "--object"
.PD
چاپ امتیاز همپوشانی در سطح شیء.
.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
تنظیم مقدار آستانه برای شمارنده داغ.
.IP \fB\-v\fR 4
.IX Item "-v"
.PD 0
.IP \fB\-\-verbose\fR 4
.IX Item "--verbose"
.PD
تنظیم حالت پرگویی.
.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)، نگارش 1.3 یا هر نگارش بعدی منتشرشده توسط بنیاد نرم‌افزارهای آزاد اعطا می‌شود؛ با بخش‌های تغییرناپذیر «GNU General Public License» و «Funding Free Software»، و متون روی جلد (الف) (در زیر) و متون پشت جلد (ب) (در زیر). نسخه‌ای از این مجوز در صفحه راهنمای \fBgfdl\fR\|(7) گنجانده شده است.
.PP
(a) The FSF\*(Aqs Front\-Cover Text is:
.PP
.Vb 1
\&     A GNU Manual
.Ve
.PP
(b) The FSF\*(Aqs Back\-Cover Text is:
.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