نام (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 ... ]

توضیحات (DESCRIPTION)

"gprof" یک پروفایل اجرایی از برنامه‌های C، Pascal، یا Fortran77 تولید می‌کند. اثر روال‌های فراخوانی‌شده در پروفایل هر فراخواننده لحاظ می‌شود. داده‌های پروفایل از فایل پروفایل نمودار فراخوانی (به‌طور پیش‌فرض gmon.out) گرفته می‌شود که توسط برنامه‌های کامپایل‌شده با گزینهٔ -pg در "cc"، "pc" و "f77" ایجاد می‌گردد. گزینهٔ -pg همچنین نسخه‌هایی از توابع کتابخانه‌ای را که برای پروفایل‌سازی کامپایل شده‌اند پیوند می‌دهد. دستور "gprof" فایل شیء (object file) ارائه‌شده (پیش‌فرض "a.out" است) را می‌خواند و رابطه میان جدول نمادهای آن و پروفایل نمودار فراخوانی را از gmon.out برقرار می‌سازد. اگر بیش از یک فایل پروفایل مشخص شده باشد، خروجی "gprof" مجموع اطلاعات پروفایل موجود در فایل‌های داده‌شده را نمایش می‌دهد.

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

انواع مختلفی از خروجی از این تحلیل در دسترس است.

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

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

فهرست annotated source رونوشتی از کد منبع برنامه است که به تعداد دفعات اجرای هر خط از برنامه برچسب‌گذاری شده است..SH "گزینه‌ها (OPTIONS)" این گزینه‌ها مشخص می‌کنند که "gprof" باید کدام‌یک از چندین قالب خروجی را تولید کند.

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

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

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

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

"-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" خروجی خود را به سبک «سنتی» (traditional) توزیع‌های BSD چاپ کند.

"-w width"

"--width=width"

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

"-x"

"--all-lines"

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

"--demangle[=style]"

"--no-demangle"

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

"-a"

"--no-static"

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

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

فایل‌ها (FILES)

"a.out"

فهرست نام‌ها (namelist) و فضای متن (کد).

"gmon.out"

گراف فراخوانی و پروفایل پویا.

"gmon.sum"

گراف فراخوانی و پروفایل پویای خلاصه‌شده.

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

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

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

برنامهٔ پروفایل‌شده باید "exit"(2) را فراخوانی کند یا به طور عادی پایان یابد تا اطلاعات پروفایل در فایل gmon.out ذخیره شوند..SH "همچنین ببینید (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-2026 Free Software Foundation, Inc.

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