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

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

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

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

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

فهرست annotated source یک نسخه از کد منبع برنامه است که با تعداد دفعات اجرای هر خط از برنامه برچسب‌گذاری شده است..SH "گزینه‌ها (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 خط از فعال‌ترین خطوط کد در هر فایل منبع فهرست شوند. مقدار پیش‌فرض ۱۰ است.

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

استفاده از آرگومان -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 تنظیم می‌کند. در حال حاضر فقط هنگام چاپ نمایهٔ توابع در انتهای نمودار فراخوانی استفاده می‌شود.

"-x"

"--all-lines"

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

"--demangle[=style]"

"--no-demangle"

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

"-a"

"--no-static"

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

"-c"

"--static-call-graph"

گزینهٔ -c باعث می‌شود گراف فراخوانی برنامه با یک روش ابتکاری (heuristic) گسترش یابد که فضای متنی فایل شیء را بررسی کرده و فراخوانی‌های توابع را در کد ماشین دودویی شناسایی می‌کند. از آنجا که رکوردهای عادی گراف فراخوانی تنها هنگام ورود به توابع تولید می‌شوند، این گزینه فرزندانی را شناسایی می‌کند که ممکن بود فراخوانی شوند، اما هرگز فراخوانی نشدند. فراخوانی‌های مربوط به توابعی که بدون فعال بودن نمایه‌سازی (profiling) کامپایل شده‌اند نیز شناسایی می‌شوند، اما تنها در صورتی که ورودی‌های جدول نمادها برای آن‌ها موجود باشد. فراخوانی روال‌های کتابخانه‌های پویا معمولاً توسط این گزینه یافت نمی‌شوند. والدین یا فرزندان شناسایی‌شده از طریق این روش ابتکاری در گراف فراخوانی با تعداد فراخوانی 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" شماره نسخهٔ فعلی را نمایش داده و سپس خارج شود.

فایل‌ها (FILES)

"a.out"

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

"gmon.out"

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

"gmon.sum"

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

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

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

والدینی که خودشان پروفایل‌بندی نشده‌اند، زمان فرزندان پروفایل‌بندی‌شدهٔ آن‌ها به آن‌ها منتقل می‌شود، اما در فهرست گراف فراخوانی به نظر می‌رسد که به طور خودبه‌خودی فراخوانی شده‌اند و زمان آن‌ها فراتر از این منتقل نخواهد شد. به همین ترتیب، گیرنده‌های سیگنال (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) منتشر شده باشد، داده می‌شود؛ بدون بخش‌های ناوردا (Invariant Sections)، بدون متن‌های روی جلد (Front-Cover Texts)، و بدون متن‌های پشت جلد (Back-Cover Texts). یک نسخه از این مجوز در بخشی با عنوان «GNU Free Documentation License» گنجانده شده است.