نام (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" یک نمایهٔ اجرایی (execution profile) از برنامه‌های C، Pascal، یا Fortran77 تولید می‌کند. اثر روتین‌های فراخوانی‌شده در نمایهٔ هر فراخواننده لحاظ می‌شود. داده‌های نمایه از فایل نمایهٔ نمودار فراخوانی (به‌طور پیش‌فرض gmon.out) خوانده می‌شوند که توسط برنامه‌های کامپایل‌شده با گزینهٔ -pg در "cc"، "pc" و "f77" ایجاد می‌گردد. همچنین گزینهٔ -pg نسخه‌هایی از روتین‌های کتابخانه‌ای را که برای نمایه‌سازی کامپایل شده‌اند پیوند (link) می‌دهد. برنامهٔ "gprof" فایل شیء (object file) داده‌شده را (به‌طور پیش‌فرض "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" ترتیب پیشنهادی توابع را برای برنامه بر اساس داده‌های پروفایل چاپ کند. این گزینه ترتیبی را پیشنهاد می‌دهد که ممکن است در سیستم‌هایی که از ترتیب دلخواه توابع در فایل اجرایی پشتیبانی می‌کنند، رفتار صفحه‌بندی (paging)، tlb و حافظهٔ نهان (cache) برنامه را بهبود بخشد.

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

"-R map_file"

"--file-ordering map_file"

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

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

آرگومان map_file مسیر فایلی است که نگاشت نام تابع به فایل شیء (object 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) شوند یا خیر. حالت پیش‌فرض، بازگردانی نمادها است. از گزینهٔ "--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 به شما امکان می‌دهد هر یالی را در گراف فراخوانی، از نمادهای منطبق با symspec from به نمادهای منطبق با symspec to حذف کنید.

"-l"

"--line"

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

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

"--inline-file-names"

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

"-m num"

"--min-count=num"

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

"-nsymspec"

"--time=symspec"

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

"-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)

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

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

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

همچنین ببینید (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)

حق نشر (c) 1988-2025 Free Software Foundation, Inc.

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