نام (NAME)

gprof - نمایش داده‌های پروفایل گراف فراخوانی

خلاصه دستور (SYNOPSIS)

gprof [ -[abcDhilLrsTvwxyz] ] [ -[ABCeEfFJnNOpPqQRStZ][name] ]
[ -I dirs ] [ -d[num] ] [ -k from/to ]
[ -m min-count ] [ -R map_file ] [ -t table-length ]
[ --[no-]annotated-source[=name] ]
[ --[no-]exec-counts[=name] ]
[ --[no-]flat-profile[=name] ] [ --[no-]graph[=name] ]
[ --[no-]time=name] [ --all-lines ] [ --brief ]
[ --debug[=level] ] [ --function-ordering ]
[ --file-ordering map_file ] [ --directory-path=dirs ]
[ --display-unused-functions ] [ --file-format=name ]
[ --file-info ] [ --help ] [ --line ] [ --inline-file-names ]
[ --min-count=n ] [ --no-static ] [ --print-path ]
[ --separate-files ] [ --static-call-graph ] [ --sum ]
[ --table-length=len ] [ --traditional ] [ --version ]
[ --width=n ] [ --ignore-non-functions ]
[ --demangle[=STYLE] ] [ --no-demangle ]
[--external-symbol-table=name]
[ image-file ] [ profile-file ... ].SH "توضیحات (DESCRIPTION)" "gprof" یک نمایهٔ اجرایی از برنامه‌های C، Pascal یا Fortran77 تولید می‌کند. اثر روتین‌های فراخوانی‌شده در نمایهٔ هر فراخواننده لحاظ می‌شود. داده‌های نمایه از فایل نمایهٔ گراف فراخوانی (به‌طور پیش‌فرض gmon.out) گرفته می‌شوند که توسط برنامه‌های کامپایل‌شده با گزینهٔ -pg در "cc"، "pc" و "f77" ایجاد شده است. گزینهٔ -pg همچنین نسخه‌هایی از روتین‌های کتابخانه‌ای را پیوند می‌دهد که برای نمایه‌سازی (profiling) کامپایل شده‌اند. "Gprof" فایل شیء داده‌شده (پیش‌فرض "a.out" است) را می‌خواند و ارتباط بین جدول نمادهای آن و نمایهٔ گراف فراخوانی از gmon.out را برقرار می‌کند. اگر بیش از یک فایل نمایه مشخص شده باشد، خروجی "gprof" مجموع اطلاعات نمایه در فایل‌های نمایهٔ ارائه‌شده را نشان می‌دهد.

"Gprof" مقدار زمان سپری‌شده در هر روتین را محاسبه می‌کند. سپس، این زمان‌ها در امتداد یال‌های گراف فراخوانی انتشار می‌یابند. چرخه‌ها (cycles) شناسایی می‌شوند، و فراخوانی‌ها به درون یک چرخه طوری تنظیم می‌شوند که در زمان آن چرخه سهیم باشند.

چندین قالب خروجی از این تحلیل در دسترس است.

نمایهٔ مسطح (flat profile) نشان می‌دهد که برنامهٔ شما چه مقدار زمان در هر تابع صرف کرده و آن تابع چند بار فراخوانی شده است. اگر صرفاً می‌خواهید بدانید کدام توابع بیشترین چرخه‌ها را مصرف می‌کنند، در اینجا به‌طور خلاصه بیان شده است.

گراف فراخوانی (call graph) برای هر تابع نشان می‌دهد که کدام توابع آن را فراخوانی کرده‌اند، آن تابع چه توابع دیگری را فراخوانی کرده است، و چند بار. همچنین تخمینی از میزان زمان سپری‌شده در زیرروتین‌های هر تابع ارائه می‌دهد. این می‌تواند مکان‌هایی را پیشنهاد دهد که شاید بتوانید در آن‌ها فراخوانی‌های تابعی را که زمان زیادی مصرف می‌کنند، حذف کنید.

فهرست کد منبع حاشیه‌نویسی‌شده (annotated source) رونوشتی از کد منبع برنامه است که با تعداد دفعات اجرای هر خط از برنامه برچسب‌گذاری شده است.

گزینه‌ها (OPTIONS)

این گزینه‌ها مشخص می‌کنند که "gprof" باید کدام‌یک از چندین قالب خروجی را تولید کند.

بسیاری از این گزینه‌ها یک symspec اختیاری برای تعیین توابعی که باید مشمول یا مستثنی شوند دریافت می‌کنند. این گزینه‌ها را می‌توان چندین بار با symspecهای مختلف مشخص کرد تا مجموعه‌هایی از نمادها مشمول یا مستثنی شوند.

مشخص کردن هر یک از این گزینه‌ها حالت پیش‌فرض (-p -q) را که یک نمایهٔ مسطح و تحلیل گراف فراخوانی برای تمام توابع چاپ می‌کند، لغو می‌کند.

"-A[symspec]"

"--annotated-source[=symspec]"

گزینهٔ -A باعث می‌شود "gprof" کد منبع حاشیه‌نویسی‌شده را چاپ کند. اگر symspec مشخص شده باشد، خروجی تنها برای نمادهای منطبق چاپ می‌شود.

"-b"

"--brief"

اگر گزینهٔ -b داده شود، "gprof" توضیحات پرگویی را که سعی در توضیح معنای تمام فیلدهای جدول‌ها دارند چاپ نمی‌کند. این گزینه در صورتی که قصد چاپ خروجی را داشته باشید، یا از دیدن این توضیحات خسته شده باشید، مفید است.

"-B"

گزینهٔ -B باعث می‌شود "gprof" تحلیل گراف فراخوانی را چاپ کند.

"-C[symspec]"

"--exec-counts[=symspec]"

گزینهٔ -C باعث می‌شود "gprof" شمارش توابع و تعداد دفعات فراخوانی هر یک را چاپ کند. اگر symspec مشخص شده باشد، شمارش تنها برای نمادهای منطبق چاپ می‌شود.

اگر فایل داده‌های نمایه حاوی رکوردهای شمارش بلوک پایه (basic-block) باشد، مشخص کردن گزینهٔ -l به همراه -C باعث می‌شود تعداد دفعات اجرای بلوک‌های پایه شمارش شده و نمایش داده شود.

"-i"

"--file-info"

گزینهٔ -i باعث می‌شود "gprof" اطلاعات خلاصه‌ای را دربارهٔ فایل(های) داده‌های نمایه نمایش داده و سپس خارج شود. تعداد رکوردهای هیستوگرام، گراف فراخوانی و شمارش بلوک‌های پایه نمایش داده می‌شود.

"-I dirs"

"--directory-path=dirs"

گزینهٔ -I فهرستی از دایرکتوری‌های جستجو را برای یافتن فایل‌های منبع مشخص می‌کند. از متغیر محیطی GPROF_PATH نیز می‌توان برای انتقال این اطلاعات استفاده کرد. بیشتر برای خروجی منبع حاشیه‌نویسی‌شده به کار می‌رود.

"-J[symspec]"

"--no-annotated-source[=symspec]"

گزینهٔ -J باعث می‌شود "gprof" کد منبع حاشیه‌نویسی‌شده را چاپ نکند. اگر symspec مشخص شده باشد، "gprof" منبع حاشیه‌نویسی‌شده را چاپ می‌کند، اما نمادهای منطبق را مستثنی می‌سازد.

"-L"

"--print-path"

به‌طور معمول، نام فایل‌های منبع بدون بخش مسیر چاپ می‌شوند. گزینهٔ -L باعث می‌شود "gprof" نام مسیر کامل فایل‌های منبع را چاپ کند، که بر اساس اطلاعات اشکال‌زدایی نمادین در فایل تصویر مشخص شده و نسبت به دایرکتوری‌ای است که کامپایلر در آن فراخوانی شده است.

"-p[symspec]"

"--flat-profile[=symspec]"

گزینهٔ -p باعث می‌شود "gprof" یک نمایهٔ مسطح را چاپ کند. اگر symspec مشخص شده باشد، نمایهٔ مسطح تنها برای نمادهای منطبق چاپ می‌شود.

"-P[symspec]"

"--no-flat-profile[=symspec]"

گزینهٔ -P باعث می‌شود "gprof" از چاپ نمایهٔ مسطح صرف‌نظر کند. اگر symspec مشخص شده باشد، "gprof" نمایهٔ مسطح را چاپ می‌کند، اما نمادهای منطبق را مستثنی می‌سازد.

"-q[symspec]"

"--graph[=symspec]"

گزینهٔ -q باعث می‌شود "gprof" تحلیل گراف فراخوانی را چاپ کند. اگر symspec مشخص شده باشد، گراف فراخوانی را تنها برای نمادهای منطبق و فرزندان آن‌ها چاپ می‌کند.

"-Q[symspec]"

"--no-graph[=symspec]"

گزینهٔ -Q باعث می‌شود "gprof" از چاپ گراف فراخوانی صرف‌نظر کند. اگر symspec مشخص شده باشد، "gprof" گراف فراخوانی را چاپ می‌کند، اما نمادهای منطبق را مستثنی می‌سازد.

"-t"

"--table-length=num"

گزینهٔ -t باعث می‌شود هنگامی که حاشیه‌نویسی منبع فعال است، num خط از فعال‌ترین خطوط کد در هر فایل منبع فهرست شوند. پیش‌فرض 10 است.

"-y"

"--separate-files"

این گزینه تنها بر خروجی منبع حاشیه‌نویسی‌شده تأثیر می‌گذارد. در حالت عادی، "gprof" فایل‌های منبع حاشیه‌نویسی‌شده را در خروجی استاندارد چاپ می‌کند. اگر این گزینه مشخص شود، منبع حاشیه‌نویسی‌شده برای فایلی به نام path/filename در فایل filename-ann تولید می‌شود. چنانچه فایل‌سیستم زیربنایی نام filename-ann را به نحوی کوتاه کند که روی filename اصلی بازنویسی شود، "gprof" در عوض منبع حاشیه‌نویسی‌شده را در فایل filename.ann تولید می‌کند (اگر نام فایل اصلی پسوند داشته باشد، آن پسوند با .ann جایگزین می‌شود).

"-Z[symspec]"

"--no-exec-counts[=symspec]"

گزینهٔ -Z موجب می‌شود "gprof" آمار شمارش توابع و تعداد دفعاتی که هر یک فراخوانی شده‌اند را چاپ نکند. اگر symspec مشخص شود، آمار چاپ می‌شود، اما نمادهای منطبق مستثنی می‌شوند.

"-r"

"--function-ordering"

گزینهٔ --function-ordering باعث می‌شود "gprof" بر اساس داده‌های تحلیل عملکرد (profiling)، ترتیب پیشنهادی توابع را برای برنامه چاپ کند. این گزینه ترتیبی را پیشنهاد می‌دهد که ممکن است در سیستم‌هایی که از چینش دلخواه توابع در یک فایل اجرایی پشتیبانی می‌کنند، رفتار paging،‏ tlb و حافظهٔ پنهان (cache) برنامه را بهبود بخشد.

جزئیات دقیق چگونگی واداشتن پیونددهنده (linker) به قرار دادن توابع در یک ترتیب خاص، وابسته به سیستم بوده و خارج از دامنهٔ این کتابچهٔ راهنما است.

"-R map_file"

"--file-ordering map_file"

گزینهٔ --file-ordering باعث می‌شود "gprof" ترتیب پیشنهادی پیوند خطوط فایلهای o. را بر اساس داده‌های profiling برای برنامه چاپ کند. این گزینه ترتیبی را پیشنهاد می‌دهد که ممکن است در سیستم‌هایی که از چینش دلخواه توابع در فایل اجرایی پشتیبانی نمی‌کنند، رفتار paging،‏ tlb و cache را برای برنامه بهبود بخشد.

استفاده از آرگومان -a همراه با این گزینه اکیداً توصیه می‌شود.

آرگومان map_file مسیر فایلی است که نگاشت نام تابع به فایل شیء را ارائه می‌دهد. قالب این فایل مشابه خروجی برنامهٔ "nm" است.

c-parse.o:00000000 T yyparse
c-parse.o:00000004 C yyerrflag
c-lang.o:00000000 T maybe_objc_method_name
c-lang.o:00000000 T print_lang_statistics
c-lang.o:00000000 T recognize_objc_keyword
c-decl.o:00000000 T print_lang_identifier
c-decl.o:00000000 T print_lang_type
...

برای ایجاد یک map_file با GNU "nm"، دستوری شبیه به این را وارد کنید: "nm --extern-only --defined-only -v --print-file-name program-name".

"-T"

"--traditional"

گزینهٔ -T باعث می‌شود "gprof" خروجی خود را به سبک «سنتی» BSD چاپ کند.

"-w width"

"--width=width"

عرض خطوط خروجی را روی width تنظیم می‌کند. در حال حاضر تنها هنگام چاپ نمایهٔ توابع در پایین نمودار فراخوانی (call graph) استفاده می‌شود.

"-x"

"--all-lines"

این گزینه تنها بر خروجی منبع حاشیه‌نویسی‌شده تأثیر می‌گذارد. به‌طور پیش‌فرض، تنها خطوط ابتدای یک بلوک پایه (basic block) حاشیه‌نویسی می‌شوند. اگر این گزینه مشخص شود، هر خط در یک بلوک پایه با تکرار حاشیه‌نویسی خط نخست حاشیه‌نویسی می‌شود. این رفتار مشابه -a در "tcov" است.

"--demangle[=style]"

"--no-demangle"

این گزینه‌ها تعیین می‌کنند که آیا نام نمادهای ++C هنگام چاپ خروجی باید demangle شوند یا خیر. پیش‌فرض بر demangle کردن نمادها است. از گزینهٔ "--no-demangle" می‌توان برای خاموش کردن demangling استفاده کرد. کامپایلرهای مختلف سبک‌های متفاوتی از mangling دارند. از آرگومان اختیاری سبک demangling می‌توان برای انتخاب سبک مناسب با کامپایلر خود استفاده کرد..SS "گزینه‌های تحلیل (Analysis Options)"

"-a"

"--no-static"

گزینهٔ -a باعث می‌شود "gprof" از چاپ توابع با اعلان ایستا (خصوصی) جلوگیری کند. (این‌ها توابعی هستند که نام‌هایشان به‌صورت سراسری فهرست نشده است و در خارج از فایل/تابع/بلوکی که در آن تعریف شده‌اند قابل مشاهده نیستند.) زمان صرف‌شده در این توابع، فراخوانی‌ها به/از آن‌ها و غیره، همگی به تابعی نسبت داده می‌شوند که در فایل اجرایی مستقیماً قبل از آن بارگذاری شده است. این گزینه هم بر پروفایل مسطح (flat profile) و هم بر گراف فراخوانی (call graph) تأثیر می‌گذارد.

"-c"

"--static-call-graph"

گزینهٔ -c باعث می‌شود گراف فراخوانی برنامه با یک روش اکتشافی (heuristic) که فضای متنی (text space) فایل شیء را بررسی کرده و فراخوانی‌های توابع را در کد باینری ماشین شناسایی می‌کند، تکمیل شود. از آنجا که رکوردهای عادی گراف فراخوانی تنها هنگام ورود به توابع تولید می‌شوند، این گزینه توابع فرزندی را شناسایی می‌کند که ممکن بود فراخوانی شوند، اما هرگز فراخوانی نشدند. فراخوانی‌ها به توابعی که با فعال بودن پروفایل‌سازی کامپایل نشده‌اند نیز شناسایی می‌شوند، اما تنها در صورتی که ورودی‌های جدول نماد برای آن‌ها وجود داشته باشد. فراخوانی‌های روال‌های کتابخانهٔ پویا معمولاً توسط این گزینه پیدا نمی‌شوند. والدین یا فرزندانی که از طریق این روش اکتشافی شناسایی می‌شوند، در گراف فراخوانی با تعداد فراخوانی 0 نشان داده می‌شوند.

"-D"

"--ignore-non-functions"

گزینهٔ -D باعث می‌شود "gprof" نمادهایی را که به‌عنوان تابع شناخته نمی‌شوند، نادیده بگیرد. این گزینه در سیستم‌هایی که از آن پشتیبانی می‌کنند (برای مثال Solaris و HPUX) داده‌های پروفایل دقیق‌تری ارائه می‌دهد.

"-k from/to"

گزینهٔ -k به شما امکان می‌دهد هر یالی (arc) در گراف فراخوانی را از نمادهای منطبق با symspec from به نمادهای منطبق با symspec to حذف کنید.

"-l"

"--line"

گزینهٔ -l پروفایل‌سازی خط‌به‌خط را فعال می‌کند، که باعث می‌شود رخدادهای هیستوگرام به جای توابع، به تک‌تک خطوط کد منبع نسبت داده شوند. این ویژگی تنها با برنامه‌هایی کار می‌کند که با نسخه‌های قدیمی‌تر کامپایلر "gcc" کامپایل شده باشند. نسخه‌های جدیدتر "gcc" برای کار با ابزار "gcov" طراحی شده‌اند.

اگر برنامه با فعال بودن شمارش بلوک‌های پایه (basic-block counting) کامپایل شده باشد، این گزینه همچنین مشخص می‌کند که هر خط از کد چند بار اجرا شده است. اگرچه پروفایل‌سازی خط‌به‌خط می‌تواند به شناسایی این‌که برنامه در کجای یک تابع بزرگ زمان خود را صرف می‌کند کمک کند، اما زمان اجرای "gprof" را نیز به‌طور قابل توجهی افزایش داده و خطاهای آماری را تشدید می‌کند.

"--inline-file-names"

این گزینه باعث می‌شود "gprof" نام فایل منبع را پس از هر نماد، هم در پروفایل مسطح و هم در گراف فراخوانی چاپ کند. در صورت استفاده با گزینهٔ -L، مسیر کامل فایل چاپ می‌شود.

"-m num"

"--min-count=num"

این گزینه تنها بر خروجی تعداد دفعات اجرا تأثیر می‌گذارد. نمادهایی که کمتر از num بار اجرا شده باشند پنهان می‌شوند.

"-nsymspec"

"--time=symspec"

گزینهٔ -n باعث می‌شود "gprof" در تحلیل گراف فراخوانی خود، زمان‌ها را تنها برای نمادهای منطبق با symspec منتشر (propagate) کند.

"-Nsymspec"

"--no-time=symspec"

گزینهٔ -N باعث می‌شود "gprof" در تحلیل گراف فراخوانی خود، زمان‌ها را برای نمادهای منطبق با symspec منتشر نکند.

"-Sfilename"

"--external-symbol-table=filename"

گزینهٔ -S باعث می‌شود "gprof" به جای خواندن جدول نماد از فایل شیء داده‌شده (پیش‌فرض "a.out" است)، یک فایل جدول نماد خارجی مانند /proc/kallsyms را بخواند. این گزینه برای پروفایل‌سازی ماژول‌های هسته مفید است.

"-z"

"--display-unused-functions"

اگر گزینهٔ -z را مشخص کنید، "gprof" تمام توابع را در پروفایل مسطح ذکر می‌کند؛ حتی توابعی که هرگز فراخوانی نشده‌اند و هیچ زمانی در آن‌ها صرف نشده است. این ویژگی همراه با گزینهٔ -c برای کشف این‌که کدام روال‌ها هرگز فراخوانی نشده‌اند مفید است..SS "گزینه‌های متفرقه (Miscellaneous Options)"

"-d[num]"

"--debug[=num]"

گزینهٔ -d num گزینه‌های اشکال‌زدایی را مشخص می‌کند. اگر num مشخص نشده باشد، تمام اشکال‌زدایی‌ها فعال می‌شوند.

"-h"

"--help"

گزینهٔ -h راهنمای استفاده از خط فرمان را چاپ می‌کند.

"-Oname"

"--file-format=name"

قالب فایل‌های دادهٔ پروفایل را انتخاب می‌کند. قالب‌های شناخته‌شده عبارتند از auto (پیش‌فرض)، bsd، 4.4bsd، magic، و prof (هنوز پشتیبانی نمی‌شود).

"-s"

"--sum"

گزینهٔ -s باعث می‌شود "gprof" اطلاعات موجود در فایل‌های دادهٔ پروفایل خوانده‌شده را خلاصه‌سازی کرده و در یک فایل دادهٔ پروفایل به نام gmon.sum بنویسد که شامل تمام اطلاعات فایل‌های دادهٔ پروفایلی است که "gprof" خوانده است. فایل gmon.sum می‌تواند یکی از فایل‌های ورودی مشخص‌شده باشد؛ اثر این کار، ادغام داده‌های سایر فایل‌های ورودی در gmon.sum خواهد بود.

در نهایت می‌توانید "gprof" را دوباره بدون -s اجرا کنید تا داده‌های تجمیعی درون فایل gmon.sum را تحلیل کند.

"-v"

"--version"

پرچم -v باعث می‌شود "gprof" شمارهٔ نسخهٔ فعلی را چاپ کرده و سپس خارج شود.

گزارش باگ‌ها (BUGS)

دانه‌بندی نمونه‌برداری نمایش داده می‌شود، اما در بهترین حالت آماری باقی می‌ماند. فرض بر این است که زمان هر بار اجرای یک تابع می‌تواند بر اساس کل زمان صرف‌شده برای تابع تقسیم بر تعداد دفعات فراخوانی آن بیان شود. بنابراین زمانی که در امتداد یال‌های گراف فراخوانی به والدین تابع منتقل می‌شود، مستقیماً متناسب با تعداد دفعات پیمایش آن یال است.

والدینی که خودشان پروفایل‌بندی نشده‌اند، زمان فرزندان پروفایل‌بندی‌شدهٔ آن‌ها به آن‌ها منتقل خواهد شد، اما به نظر می‌رسد که در فهرست گراف فراخوانی به‌صورت خودبه‌خودی فراخوانی شده‌اند و زمان آن‌ها فراتر از این منتقل نخواهد شد. به‌طور مشابه، گیرنده‌های سیگنال (signal catchers)، حتی اگر پروفایل‌بندی شده باشند، خودبه‌خودی به نظر خواهند رسید (اگرچه به دلایلی مبهم‌تر). زمان هر یک از فرزندان پروفایل‌بندی‌شدهٔ گیرنده‌های سیگنال باید به‌درستی منتقل شود، مگر اینکه گیرندهٔ سیگنال در طول اجرای روال پروفایل‌بندی فراخوانی شده باشد، که در این صورت همه چیز از دست می‌رود.

برنامهٔ پروفایل‌بندی‌شده باید "exit"(2) را فراخوانی کند یا به‌طور عادی بازگردد تا اطلاعات پروفایل‌بندی در فایل gmon.out ذخیره شود.

همچنین ببینید (SEE ALSO)

monitor(3), profil(2), cc(1), prof(1)، و مدخل Info برای gprof.

"An Execution Profiler for Modular Programs", نوشتهٔ S. Graham, P. Kessler, M. McKusick; Software - Practice and Experience, Vol. 13, pp. 671-685, 1983.

"gprof: A Call Graph Execution Profiler", نوشتهٔ S. Graham, P. Kessler, M. McKusick; Proceedings of the SIGPLAN '82 Symposium on Compiler Construction, SIGPLAN Notices, Vol. 17, No 6, pp. 120-126, June 1982.

کپی‌رایت و تکثیر (COPYRIGHT)

Copyright (c) 1988-2025 Free Software Foundation, Inc.

اجازهٔ کپی، توزیع و/یا تغییر این سند تحت شرایط «مجوز مستندات آزاد گنو» (GNU Free Documentation License)، نسخهٔ 1.3 یا هر نسخهٔ متأخرتری که توسط بنیاد نرم‌افزار آزاد منتشر شده باشد، داده می‌شود؛ بدون بخش‌های ناوردا، بدون متن‌های روی جلد و بدون متن‌های پشت جلد. نسخه‌ای از این مجوز در بخشی با عنوان "GNU Free Documentation License" گنجانده شده است.