.\" -*- 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 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
ادغام دو مجموعه پروفایل با اعمال ضریب وزنی (weights).
.IP * 4
خواندن جریانی از پروفایل‌ها به همراه نام فایل‌های مربوطه و ادغام آن با مجموعه‌ای از پروفایل‌ها با اعمال ضریب وزنی.
.IP * 4
خواندن یک مجموعه از پروفایل و بازنویسی محتوای آن. می‌توان مقادیر شمارنده‌ها را مقیاس‌بندی (scale) یا نرمال‌سازی (normalize) کرد.
.PP
نمونه‌هایی از موارد کاربرد این ابزار عبارتند از:
.IP * 4
جمع‌آوری پروفایل‌ها برای مجموعه‌های مختلف ورودی، و استفاده از این ابزار برای ادغام آنها. می‌توان ضریب وزنی را برای در نظر گرفتن اهمیت نسبی هر ورودی مشخص کرد.
.IP * 4
جمع‌آوری پروفایل‌ها از سیستم‌های مقصد فاقد سیستم‌فایل (محیط‌های مستقل یا freestanding). ادغام پروفایل‌های جمع‌آوری‌شده با پروفایل‌های متناظر موجود در سیستم میزبان. می‌توان وزن را برای تعیین اهمیت نسبی هر ورودی مشخص نمود.
.IP * 4
بازنویسی پروفایل پس از حذف زیرمجموعه‌ای از فایل‌های gcda، ضمن حفظ یکپارچگی خلاصه (summary) و هیستوگرام (histogram).
.IP * 4
همچنین می‌توان از آن برای اشکال‌زدایی کد libgcov استفاده کرد، زیرا این ابزار اکثر کدهای خود را با کتابخانه زمان اجرا به اشتراک می‌گذارد.
.PP
توجه داشته باشید که در عملیات ادغام، پروفایل ایجادشده به‌صورت آفلاین ممکن است مقادیر اندک متفاوتی نسبت به پروفایل ادغام‌شده آنلاین داشته باشد. در اینجا فهرستی از تفاوت‌های معمول آورده شده است:
.IP * 4
تفاوت هیستوگرام: این ابزار آفلاین پس از ادغام شمارنده‌ها، هیستوگرام را دوباره محاسبه می‌کند؛ بنابراین هیستوگرام حاصل دقیق است. ادغام آنلاین این قابلیت را ندارد \-\- هیستوگرام از دو هیستوگرام ادغام می‌شود و نتیجه یک تقریب است.
.IP * 4
تفاوت چکسام خلاصه (summary checksum): چکسام خلاصه از عملیات 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
فعال‌سازی حالت پرگویی (verbose).
.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
فعال‌سازی حالت پرگویی (verbose).
.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
مقیاس‌بندی شمارنده‌های پروفایل. مقدار مشخص‌شده می‌تواند به‌صورت یک مقدار اعشاری ممیز شناور (floating point) یا کسری ساده مانند 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
فعال‌سازی حالت پرگویی (verbose).
.RE
.RS 4
.RE
.IP \fBoverlap\fR 4
.IX Item "overlap"
محاسبه امتیاز همپوشانی (overlap score) میان دو پوشه پروفایل مشخص‌شده. امتیاز همپوشانی بر اساس پروفایل‌های کمان (arc profiles) محاسبه می‌شود. این امتیاز به‌صورت مجموع 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).
.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"
حق نشر \(co ۲۰۱۴\-۲۰۲۶ بنیاد نرم‌افزارهای آزاد (Free Software Foundation, Inc.)
.PP
اجازه کپی، توزیع و/یا تغییر این سند تحت شرایط «مجوز مستندات آزاد گنو» (GNU Free Documentation License)، نسخه ۱.۳ یا هر نسخه بعدی منتشرشده توسط بنیاد نرم‌افزارهای آزاد اعطا می‌شود؛ با بخش‌های تغییرناپذیر «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