Return to gprof.1 CVS log

Up to [Power 6/32 Unix Tahoe 4.2BSD] / cci / usr / src / man / man1

Annotation of cci/usr/src/man/man1/gprof.1, revision 1.1

1.1     ! root        1: .TH GPROF 1 "18 January 1983"
        !             2: \"     @(#)gprof.1     1.9 (Berkeley) 10/12/82
        !             3: .UC 4
        !             4: .SH NAME
        !             5: gprof \- display call graph profile data
        !             6: .SH SYNOPSIS
        !             7: .B gprof
        !             8: [ options ] [ a.out [ gmon.out ... ] ]
        !             9: .SH DESCRIPTION
        !            10: .I gprof
        !            11: produces an execution profile of C, Pascal, or Fortran77 programs.
        !            12: The effect of called routines is incorporated in the profile of each caller.
        !            13: The profile data is taken from the call graph profile file
        !            14: .RI ( gmon.out
        !            15: default) which is created by programs
        !            16: which are compiled with the 
        !            17: .B \-pg
        !            18: option of 
        !            19: .IR cc ,
        !            20: .IR pc ,
        !            21: and
        !            22: .IR f77 .
        !            23: That option also links in versions of the library routines 
        !            24: which are compiled for profiling.
        !            25: The symbol table in the
        !            26: named object file
        !            27: .RI ( a.out
        !            28: default)
        !            29: is read and correlated with the
        !            30: call graph profile file.
        !            31: If more than one profile file is specified,
        !            32: the
        !            33: .I gprof
        !            34: output shows the sum of the profile information in the given profile files.
        !            35: .PP
        !            36: First, a flat profile is given,
        !            37: similar to that provided by
        !            38: .IR prof (1).
        !            39: This listing gives the total execution times
        !            40: and call counts for each of the functions
        !            41: in the program, sorted by decreasing time.
        !            42: .PP
        !            43: Next, these times are propagated along the edges of the call graph.
        !            44: Cycles are discovered, and calls into a cycle are made to share the time 
        !            45: of the cycle.
        !            46: A second listing shows the functions
        !            47: sorted according to the time they represent
        !            48: including the time of their call graph descendents.
        !            49: Below each function entry is shown its (direct) call graph children,
        !            50: and how their times are propagated to this function.
        !            51: A similar display above the function shows how this function's time and the
        !            52: time of its descendents is propagated to its (direct) call graph parents.
        !            53: .PP
        !            54: Cycles are also shown, with an entry for the cycle as a whole and
        !            55: a listing of the members of the cycle and their contributions to the
        !            56: time and call counts of the cycle.
        !            57: .PP
        !            58: The following options are available:
        !            59: .TP
        !            60: .B \-a
        !            61: suppresses the printing of statically declared functions.
        !            62: If this option is given, all relevant information about the static function
        !            63: .RI ( e.g.,
        !            64: time samples, calls to other functions, calls from other functions)
        !            65: belongs to the function loaded just before the static function in the
        !            66: .I a.out
        !            67: file.
        !            68: .TP
        !            69: .B \-b
        !            70: supresses the printing of a description of each field in the profile.
        !            71: .TP
        !            72: .B \-c
        !            73: the static call graph of the program is discovered by a heuristic
        !            74: which examines the text space of the object file.
        !            75: Static-only parents or children are indicated
        !            76: with call counts of 0.
        !            77: .TP
        !            78: .BI \-e " name"
        !            79: suppresses the printing of the graph profile entry for routine
        !            80: .I name
        !            81: and all its descendants
        !            82: (unless they have other ancestors that aren't suppressed).
        !            83: More than one
        !            84: .B \-e
        !            85: option may be given.
        !            86: Only one
        !            87: .I name
        !            88: may be given with each
        !            89: .B \-e
        !            90: option.
        !            91: .TP
        !            92: .BI \-E " name"
        !            93: suppresses the printing of the graph profile entry for routine
        !            94: .I name
        !            95: (and its descendants) as 
        !            96: .BR \-e ,
        !            97: above, and also excludes the time spent in
        !            98: .I name
        !            99: (and its descendants) from the total and percentage time computations.
        !           100: (For example,
        !           101: .B \-E
        !           102: .I mcount
        !           103: .B \-E
        !           104: .I mcleanup
        !           105: is the default.)
        !           106: .TP
        !           107: .BI \-f " name"
        !           108: prints the graph profile entry of only the specified routine
        !           109: .I name
        !           110: and its descendants.
        !           111: More than one
        !           112: .B \-f
        !           113: option may be given.
        !           114: Only one
        !           115: .I name
        !           116: may be given with each
        !           117: .B \-f
        !           118: option.
        !           119: .TP
        !           120: .BI \-F " name"
        !           121: prints the graph profile entry of only the routine
        !           122: .I name
        !           123: and its descendants (as 
        !           124: .BR \-f,
        !           125: above) and also uses only the times of the printed routines
        !           126: in total time and percentage computations.
        !           127: More than one
        !           128: .B \-F
        !           129: option may be given.
        !           130: Only one
        !           131: .I name
        !           132: may be given with each
        !           133: .B \-F
        !           134: option.
        !           135: The
        !           136: .B \-F
        !           137: option
        !           138: overrides
        !           139: the
        !           140: .B \-E
        !           141: option.
        !           142: .TP
        !           143: .B \-s
        !           144: a profile file
        !           145: .I gmon.sum
        !           146: is produced which represents
        !           147: the sum of the profile information in all the specified profile files.
        !           148: This summary profile file may be given to subsequent
        !           149: executions of gprof (probably also with a
        !           150: .BR \-s )
        !           151: to accumulate profile data across several runs of an
        !           152: .I a.out
        !           153: file.
        !           154: .TP
        !           155: .B \-z
        !           156: displays routines which have zero usage (as indicated by call counts
        !           157: and accumulated time).
        !           158: This is useful in conjunction with the 
        !           159: .B \-c
        !           160: option for discovering which routines were never called.
        !           161: .SH FILES
        !           162: .ta 1.5i
        !           163: .I a.out       
        !           164: the namelist and text space.
        !           165: .br
        !           166: .I gmon.out    
        !           167: dynamic call graph and profile.
        !           168: .br
        !           169: .I gmon.sum    
        !           170: summarized dynamic call graph and profile.
        !           171: .SH "SEE ALSO"
        !           172: monitor(3), profil(2), cc(1), prof(1)
        !           173: .br
        !           174: ``gprof: A Call Graph Execution Profiler'', by
        !           175: Graham, S.L., Kessler, P.B., McKusick, M.K.;
        !           176: .IR "Proceedings of the SIGPLAN '82 Symposium on Compiler Construction" ,
        !           177: SIGPLAN Notices, Vol. 17, No. 6, pp. 120-126, June 1982.
        !           178: .SH BUGS
        !           179: Beware of quantization errors.
        !           180: The granularity of the sampling is shown, but remains
        !           181: statistical at best.
        !           182: We assume that the time for each execution of a function
        !           183: can be expressed by the total time for the function divided
        !           184: by the number of times the function is called.
        !           185: Thus the time propagated along the call graph arcs to parents of that
        !           186: function is directly proportional to the number of times that
        !           187: arc is traversed.
        !           188: .PP
        !           189: Parents which are not themselves profiled will have the time of 
        !           190: their profiled children propagated to them, but they will appear
        !           191: to be spontaneously invoked in the call graph listing, and will
        !           192: not have their time propagated further.
        !           193: Similarly, signal catchers, even though profiled, will appear
        !           194: to be spontaneous (although for more obscure reasons).
        !           195: Any profiled children of signal catchers should have their times
        !           196: propagated properly, unless the signal catcher was invoked during 
        !           197: the execution of the profiling routine, in which case all is lost.
        !           198: .PP
        !           199: The profiled program must call 
        !           200: .IR exit (2)
        !           201: or return normally for the profiling information to be saved
        !           202: in the gmon.out file.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.