Return to gprof.1 CVS log

Up to [CSRG BSD Unix] / 43BSDTahoe / man / man1

Annotation of 43BSDTahoe/man/man1/gprof.1, revision 1.1

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

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