نام (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 همچنین نسخه‌هایی از روال‌های کتابخانه‌ای را پیوند می‌دهد که برای نمایه‌سازی کامپایل شده‌اند. "Gprof" فایل شیء داده‌شده را می‌خواند (پیش‌فرض "a.out" است) و ارتباط میان جدول نمادهای آن و نمایهٔ گراف فراخوانی را از gmon.out برقرار می‌سازد. اگر بیش از یک فایل نمایه مشخص شده باشد، خروجی "gprof" مجموع اطلاعات نمایه را در فایل‌های نمایهٔ ارائه‌شده نمایش می‌دهد.

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

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

نمایهٔ تخت (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) برنامه را در سیستم‌هایی که از ترتیب دلخواه توابع در یک فایل اجرایی پشتیبانی می‌کنند، بهبود بخشد.

جزئیات دقیق نحوهٔ وادار کردن پیونددهنده به قرار دادن توابع در یک ترتیب خاص، وابسته به سیستم بوده و خارج از محدودهٔ این راهنما است.

"-R map_file"

"--file-ordering map_file"

گزینهٔ --file-ordering باعث می‌شود "gprof" یک ترتیب پیشنهادی خط پیوند برای فایل‌های .o برنامه بر اساس داده‌های پروفایلینگ چاپ کند. این گزینه ترتیبی را پیشنهاد می‌دهد که ممکن است رفتار صفحه‌بندی، 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" می‌تواند برای غیرفعال کردن خواناسازی استفاده شود. کامپایلرهای مختلف شیوه‌های درهم‌سازی (mangling) متفاوتی دارند. از آرگومان اختیاری سبک demangling می‌توان برای انتخاب سبک مناسب با کامپایلر خود استفاده کرد..SS "گزینه‌های تحلیل (Analysis Options)"

"-a"

"--no-static"

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

"-c"

"--static-call-graph"

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

"-D"

"--ignore-non-functions"

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

"-k from/to"

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

"-l"

"--line"

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

اگر برنامه با فعال بودن شمارش بلوک‌های پایه (basic-block counting) کامپایل شده باشد، این گزینه همچنین مشخص خواهد کرد که هر خط از کد چند بار اجرا شده است. اگرچه تحلیل خط‌به‌خط می‌تواند به جداسازی بخشی از یک تابع بزرگ که برنامه زمان خود را در آن سپری می‌کند کمک کند، اما زمان اجرای "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 گزینه‌های اشکال‌زدایی (debugging) را مشخص می‌کند. اگر num مشخص نشده باشد، تمام اشکال‌زدایی‌ها فعال می‌شوند.

"-h"

"--help"

گزینه -h نحوه استفاده از خط فرمان را نمایش می‌دهد.

"-Oname"

"--file-format=name"

قالب فایل‌های داده نمایه (profile data) را انتخاب می‌کند. قالب‌های شناخته‌شده عبارتند از 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) نمونه‌برداری نشان داده می‌شود، اما در بهترین حالت ماهیتی آماری دارد. فرض بر این است که زمان هر بار اجرای یک تابع را می‌توان به‌صورت کل زمان صرف‌شده در آن تابع تقسیم بر تعداد دفعات فراخوانی‌اش نشان داد. بنابراین، زمانی که در طول یال‌های گراف فراخوانی به والدینِ تابع منتقل می‌شود، با تعداد دفعات پیموده شدن آن یال رابطهٔ مستقیم دارد.

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

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

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

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

"An Execution Profiler for Modular Programs", by S. Graham, P. Kessler, M. McKusick; Software - Practice and Experience, Vol. 13, pp. 671-685, 1983.

"gprof: A Call Graph Execution Profiler", by 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)، نسخهٔ ۱.۳ یا هر نسخهٔ متأخرتری که توسط بنیاد نرم‌افزارهای آزاد (Free Software Foundation) منتشر شده است اعطا می‌شود؛ بدون هیچ بخش تغییرناپذیر، بدون متن روی جلد، و بدون متن پشت جلد. یک نسخه از این مجوز در بخشی با عنوان «GNU Free Documentation License» گنجانده شده است.