GPROF(1)

الاسم
gprof - يعرض بيانات تشكيلة مخطط الاستدعاء

موجز
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 ... ]

الوصف
"gprof" يُنتج تشكيلة تنفيذ لبرامج C، أو Pascal، أو Fortran77. تُدمج تأثيرات الروتينات المستدعاة في تشكيلة كل مستدعٍ. تُؤخذ بيانات التشكيلة من ملف تشكيلة مخطط الاستدعاء (المبدئي gmon.out) الذي تُنشئه البرامج المجمعة بالخيار -pg لكل من "cc"، و "pc"، و "f77". يربط الخيار -pg أيضًا نسخًا من روتينات المكتبة المجمعة لأغراض التشكيلة. يقرأ "Gprof" ملف الكائن المعطى (المبدئي هو "a.out") ويؤسس العلاقة بين جدول رموزه وتشكيلة مخطط الاستدعاء من gmon.out. إذا حُدد أكثر من ملف تشكيلة واحد، يُظهر خرج "gprof" مجموع معلومات التشكيلة في ملفات التشكيلة المعطاة.

إذا استخدمت gcc 2.95.x أو 3.0 لتجميع ملفاتك الثنائية، فقد تحتاج إلى إضافة -fprofile-arcs إلى سطر أوامر التجميع حتى يتم تخزين مخططات الاستدعاء بشكل صحيح في gmon.out.

يحسب "Gprof" مقدار الوقت المستغرق في كل روتين. بعد ذلك، تُنشر هذه الأوقات عبر حواف مخطط الاستدعاء. تُكتشف الدورات، وتُجعل الاستدعاءات داخل الدورة تتشارك وقت الدورة.

تتوفر عدة أشكال للمخرجات من التحليل.

تُظهر التشكيلة المسطحة مقدار الوقت الذي قضاه برنامجك في كل دالة، وعدد المرات التي استُدعيت فيها تلك الدالة. إذا كنت تريد ببساطة معرفة الدوال التي تستهلك معظم الدورات، فسيُذكر ذلك بإيجاز هنا.

يُظهر مخطط الاستدعاء، لكل دالة، الدوال التي استدعتها، والدوال الأخرى التي استدعتها هي، وعدد المرات. يوجد أيضًا تقدير لمقدار الوقت الذي قُضي في الروتينات الفرعية لكل دالة. يمكن أن يقترح هذا أماكن قد تحاول فيها استبعاد استدعاءات الدوال التي تستهلك الكثير من الوقت.

قائمة المصدر المشروح هي نسخة من كود مصدر البرنامج، موسومة بعدد المرات التي نُفذ فيها كل سطر من البرنامج.

الخيارات
تحدد هذه الخيارات أي شكل من أشكال المخرجات المتعددة يجب أن ينتجها "gprof".

تأخذ العديد من هذه الخيارات symspec اختيارياً لتحديد الدوال التي سيتم تضمينها أو استبعادها. يمكن تحديد هذه الخيارات عدة مرات، مع symspecs مختلفة، لتضمين أو استبعاد مجموعات من الرموز.

تحديد أي من هذه الخيارات يتجاوز المبدئي (-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، فسيُطبع الإحصاء فقط للرموز المطابقة.

    إذا كان ملف بيانات التشكيلة يحتوي على سجلات عدد الكتل البرمجية الأساسية، فإن تحديد الخيار -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، و الخبيئة للبرنامج على الأنظمة التي لا تدعم الترتيب العشوائي للدوال في ملف تنفيذي.

    يُنصح بشدة باستخدام المعامل -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 باستخدام جنو "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"
    يؤثر هذا الخيار على مخرجات المصدر المشروح فقط. مبدئياً، يتم فقط شرح الأسطر في بداية الكتلة البرمجية الأساسية. إذا حُدد هذا الخيار، فسيتم شرح كل سطر في الكتلة الأساسية عن طريق تكرار شرح السطر الأول. هذا السلوك مشابه لـ -a في "tcov".

"--demangle[=style]"
"--no-demangle"
    تتحكم هذه الخيارات في ما إذا كان يجب فك تشويه (demangle) أسماء رموز C++ عند طباعة المخرجات. المبدئي هو فك تشويه الرموز. يمكن استخدام الخيار "--no-demangle" لإيقاف فك التشويه. للمجمعات المختلفة أساليب تشويه مختلفة. يمكن استخدام معامل نمط فك التشويه الاختياري لاختيار نمط فك تشويه مناسب لمجمعك.

  خيارات التحليل

"-a"
"--no-static"
    يؤدي الخيار -a إلى قيام "gprof" بمنع طباعة الدوال المصرح عنها ساكنًا (خاصة). (هذه هي الدوال التي لا تُدرج أسماؤها كعالمية، والتي لا تكون مرئية خارج الملف/الدالة/الكتلة التي عُرّفت فيها.) الوقت المستغرق في هذه الدوال، والاستدعاءات منها وإليها، وما إلى ذلك، ستُنسب جميعها إلى الدالة التي حُمّلت مباشرة قبلها في الملف التنفيذي. يؤثر هذا الخيار على كل من التشكيلة المسطحة ومخطط الاستدعاء.

"-c"
"--static-call-graph"
    يؤدي الخيار -c إلى تعزيز مخطط استدعاء البرنامج بواسطة الكشف الذي يفحص مساحة النص لملف الكائن ويحدد استدعاءات الدوال في كود الآلة الثنائي. نظرًا لأن سجلات مخطط الاستدعاء العادية تُولد فقط عند الدخول إلى الدوال، فإن هذا الخيار يحدد الأبناء الذين كان من الممكن استدعاؤهم، لكن لم يتم استدعاؤهم أبدًا. كما يتم تحديد استدعاءات الدوال التي لم تُجمع مع تمكين التشكيلة، ولكن فقط إذا كانت مدخلات جدول الرموز موجودة لها. استدعاءات روتينات المكتبة الديناميكية عادةً لا تُوجد بهذا الخيار. يُشار إلى الآباء أو الأبناء الذين حُددوا عبر هذا الكشف في مخطط الاستدعاء بعدد استدعاءات يبلغ 0.

"-D"
"--ignore-non-functions"
    يؤدي الخيار -D إلى قيام "gprof" بتجاهل الرموز التي لا تُعرف بأنها دوال. سيعطي هذا الخيار بيانات تشكيلة أكثر دقة على الأنظمة التي تدعمه (Solaris و HPUX على سبيل المثال).

"-k from/to"
    يسمح لك الخيار -k بحذف أي أقواس من مخطط الاستدعاء من الرموز المطابقة لـ symspec from إلى تلك المطابقة لـ symspec to.

"-l"
"--line"
    يُمكن الخيار -l التشكيلة سطراً بسطر، مما يؤدي إلى احتساب ضربات المدرج التكراري لأسطر كود المصدر الفردية، بدلاً من الدوال. تعمل هذه الميزة فقط مع البرامج المجمعة بواسطة إصدارات قديمة من مجمع "gcc". الإصدارات الأحدث من "gcc" مصممة للعمل مع أداة "gcov" بدلاً من ذلك.

    إذا جُمّع البرنامج مع تمكين عد الكتل الأساسية، فسيحدد هذا الخيار أيضًا عدد مرات تنفيذ كل سطر من الكود. بينما يمكن أن تساعد التشكيلة سطراً بسطر في عزل مكان قضاء البرنامج لوقته داخل دالة كبيرة، إلا أنها تزيد أيضًا بشكل كبير من وقت تشغيل "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" بقراءة ملف جدول رموز خارجي، مثل /proc/kallsyms، بدلاً من قراءة جدول الرموز من ملف الكائن المعطى (المبدئي هو "a.out"). هذا مفيد لتشكيل وحدات النواة.

"-z"
"--display-unused-functions"
    إذا أعطيت الخيار -z، فسيذكر "gprof" جميع الدوال في التشكيلة المسطحة، حتى تلك التي لم تُستدع أبدًا، والتي لم يُقض أي وقت فيها. هذا مفيد بالاقتران مع الخيار -c لاكتشاف الروتينات التي لم تُستدع أبدًا.

  خيارات متنوعة

"-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" بطباعة رقم الإصدار الحالي، ثم الخروج.

  خيارات مهجورة
استُبدلت هذه الخيارات بإصدارات أحدث تستخدم symspecs.

"-e function_name"
    يخبر الخيار -e function برنامج "gprof" بعدم طباعة معلومات حول الدالة function_name (وأبنائها...) في مخطط الاستدعاء. ستظل الدالة مدرجة كابن لأي دوال تستدعيها، ولكن رقم فهرسها سيظهر كـ [not printed]. يمكن إعطاء أكثر من خيار -e؛ ويمكن تحديد function_name واحد فقط مع كل خيار -e.

"-E function_name"
    يعمل الخيار "-E function" مثل الخيار "-e"، ولكن الوقت المستغرق في الدالة (والأبناء الذين لم يستدعوا من أي مكان آخر)، لن يُستخدم لحساب النسب المئوية للوقت لمخطط الاستدعاء. يمكن إعطاء أكثر من خيار -E؛ ويمكن تحديد function_name واحد فقط مع كل خيار -E.

"-f function_name"
    يؤدي الخيار -f function إلى قيام "gprof" بقصر مخطط الاستدعاء على الدالة function_name وأبنائها (وأبنائهم...). يمكن إعطاء أكثر من خيار -f؛ ويمكن تحديد function_name واحد فقط مع كل خيار -f.

"-F function_name"
    يعمل الخيار -F function مثل الخيار "-f"، ولكن فقط الوقت المستغرق في الدالة وأبنائها (وأبنائهم...) سيُستخدم لتحديد الوقت الإجمالي والنسب المئوية للوقت لمخطط الاستدعاء. يمكن إعطاء أكثر من خيار -F؛ ويمكن تحديد function_name واحد فقط مع كل خيار -F. يتجاوز الخيار -F الخيار -E.

الملفات

"a.out"
    قائمة الأسماء ومساحة النص.

"gmon.out"
    مخطط الاستدعاء الديناميكي والتشكيلة.

"gmon.sum"
    مخطط الاستدعاء الديناميكي والتشكيلة الملخصة.

العلل
تُعرض دقة المعاينة، لكنها تظل إحصائية في أحسن الأحوال. نفترض أن الوقت لكل تنفيذ لدالة يمكن التعبير عنه بالوقت الإجمالي للدالة مقسوماً على عدد مرات استدعاء الدالة. وبالتالي فإن الوقت المنشور عبر أقواس مخطط الاستدعاء إلى آباء الدالة يتناسب طردياً مع عدد مرات اجتياز ذلك القوس.

الآباء الذين لم يتم تشكيلهم بأنفسهم سيتم نشر وقت أبنائهم المشكلين إليهم، لكنهم سيظهرون وكأنهم استُدعوا تلقائياً في قائمة مخطط الاستدعاء، ولن يُنشر وقتهم بشكل أكبر. وبالمثل، فإن مقتنصي الإشارات (signal catchers)، على الرغم من تشكيلهم، سيظهرون وكأنهم تلقائيون (وإن كان لأسباب أكثر غموضاً). يجب أن يُنشر وقت أي أبناء مشكلين لمقتنصي الإشارات بشكل صحيح، ما لم يُستدع مقتنص الإشارة أثناء تنفيذ روتين التشكيلة، وفي هذه الحالة يُفقد كل شيء.

يجب أن يستدعي البرنامج المشكل "exit"(2) أو يعود بشكل طبيعي ليتم حفظ معلومات التشكيلة في الملف gmon.out.

انظر أيضًا
cc(1)، و prof(1)، ومدخل Info لـ gprof.

"An Execution Profiler for Modular Programs"، بقلم S. Graham، P. Kessler، M. McKusick؛ Software - Practice and Experience، المجلد 13، ص 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، المجلد 17، العدد 6، ص 120-126، يونيو 1982.

حقوق النسخ
حقوق النشر (c) 1988-2026 مؤسسة البرمجيات الحرة، المحدودة.

يُمنح الإذن بنسخ وتوزيع و/أو تعديل هذا المستند بموجب شروط رخصة جنو للوثائق الحرة (GNU Free Documentation License)، الإصدار 1.3 أو أي إصدار لاحق تنشره مؤسسة البرمجيات الحرة؛ مع عدم وجود أقسام ثابتة، وبدون نصوص غلاف أمامي، وبدون نصوص غلاف خلفي. نُسخة من الرخصة مضمنة في القسم المعنون "GNU Free Documentation License".

ترجمة
تُرجمت هذه الصفحة من الدليل بواسطة زايد السعيدي <zayed.alsaidi@gmail.com>

هذه الترجمة هي وثيقة مجانية؛ راجع رخصة جنو العامة الإصدار 3 (https://www.gnu.org/licenses/gpl-3.0.html) أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.

إذا وجدت أي أخطاء في ترجمة صفحة الدليل هذه، يرجى إرسال بريد إلكتروني إلى قائمة بريد المترجمين: kde-l10n-ar@kde.org.