Return to gprof.1 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / pgrm / gprof

Annotation of 43BSDReno/pgrm/gprof/gprof.1, revision 1.1

1.1     ! root        1: .\" Copyright (c) 1983, 1990 The Regents of the University of California.
        !             2: .\" All rights reserved.
        !             3: .\"
        !             4: .\" Redistribution and use in source and binary forms are permitted provided
        !             5: .\" that: (1) source distributions retain this entire copyright notice and
        !             6: .\" comment, and (2) distributions including binaries display the following
        !             7: .\" acknowledgement:  ``This product includes software developed by the
        !             8: .\" University of California, Berkeley and its contributors'' in the
        !             9: .\" documentation or other materials provided with the distribution and in
        !            10: .\" all advertising materials mentioning features or use of this software.
        !            11: .\" Neither the name of the University nor the names of its contributors may
        !            12: .\" be used to endorse or promote products derived from this software without
        !            13: .\" specific prior written permission.
        !            14: .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
        !            15: .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
        !            16: .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
        !            17: .\"
        !            18: .\"     @(#)gprof.1    6.6 (Berkeley) 7/24/90
        !            19: .\"
        !            20: .Dd July 24, 1990
        !            21: .Dt GPROF 1
        !            22: .Os BSD 4.2
        !            23: .Sh NAME
        !            24: .Nm gprof
        !            25: .Nd display call graph profile data
        !            26: .Sh SYNOPSIS
        !            27: .Nm gprof
        !            28: .Op options
        !            29: .Op Ar a.out Op Ar gmon.out ...
        !            30: .Sh DESCRIPTION
        !            31: .Nm gprof
        !            32: produces an execution profile of C, Pascal, or Fortran77 programs.
        !            33: The effect of called routines is incorporated in the profile of each caller.
        !            34: The profile data is taken from the call graph profile file
        !            35: .Pf \&( Pa gmon.out
        !            36: default) which is created by programs
        !            37: that are compiled with the
        !            38: .Fl pg
        !            39: option of
        !            40: .Xr cc 1 ,
        !            41: .Xr pc 1 ,
        !            42: and
        !            43: .Xr f77 1 .
        !            44: The
        !            45: .Fl pg
        !            46: option also links in versions of the library routines
        !            47: that are compiled for profiling.
        !            48: .Nm Gprof
        !            49: reads the given object file (the default is
        !            50: .Pa a.out)
        !            51: and establishes the relation between it's symbol table
        !            52: and the call graph profile from
        !            53: .Pa gmon.out .
        !            54: If more than one profile file is specified,
        !            55: the
        !            56: .Nm gprof
        !            57: output shows the sum of the profile information in the given profile files.
        !            58: .Pp
        !            59: .Nm Gprof
        !            60: calculates the amount of time spent in each routine.
        !            61: Next, these times are propagated along the edges of the call graph.
        !            62: Cycles are discovered, and calls into a cycle are made to share the time
        !            63: of the cycle.
        !            64: The first listing shows the functions
        !            65: sorted according to the time they represent
        !            66: including the time of their call graph descendents.
        !            67: Below each function entry is shown its (direct) call graph children,
        !            68: and how their times are propagated to this function.
        !            69: A similar display above the function shows how this function's time and the
        !            70: time of its descendents is propagated to its (direct) call graph parents.
        !            71: .Pp
        !            72: Cycles are also shown, with an entry for the cycle as a whole and
        !            73: a listing of the members of the cycle and their contributions to the
        !            74: time and call counts of the cycle.
        !            75: .Pp
        !            76: Second, a flat profile is given,
        !            77: similar to that provided by
        !            78: .Xr prof  1  .
        !            79: This listing gives the total execution times, the call counts,
        !            80: the time in milleseconds the call spent in the routine itself, and
        !            81: the time in milleseconds the call spent in the routine itself including
        !            82: its descendents.
        !            83: .Pp
        !            84: Finally, an index of the function names is provided.
        !            85: .Pp
        !            86: The following options are available:
        !            87: .Tw Fl
        !            88: .Tp Fl a
        !            89: suppresses the printing of statically declared functions.
        !            90: If this option is given, all relevant information about the static function
        !            91: (e.g., time samples, calls to other functions, calls from other functions)
        !            92: belongs to the function loaded just before the static function in the
        !            93: .Pa a.out
        !            94: file.
        !            95: .Tp Fl b
        !            96: suppresses the printing of a description of each field in the profile.
        !            97: .Tp Fl c
        !            98: the static call graph of the program is discovered by a heuristic
        !            99: that examines the text space of the object file.
        !           100: Static-only parents or children are shown
        !           101: with call counts of 0.
        !           102: .Tc Fl e
        !           103: .Ws
        !           104: .Ar name
        !           105: .Cx
        !           106: suppresses the printing of the graph profile entry for routine
        !           107: .Ar name
        !           108: and all its descendants
        !           109: (unless they have other ancestors that aren't suppressed).
        !           110: More than one
        !           111: .Fl e
        !           112: option may be given.
        !           113: Only one
        !           114: .Ar name
        !           115: may be given with each
        !           116: .Fl e
        !           117: option.
        !           118: .Tc Fl E
        !           119: .Ws
        !           120: .Ar name
        !           121: .Cx
        !           122: suppresses the printing of the graph profile entry for routine
        !           123: .Ar name
        !           124: (and its descendants) as
        !           125: .Fl e  ,
        !           126: above, and also excludes the time spent in
        !           127: .Ar name
        !           128: (and its descendants) from the total and percentage time computations.
        !           129: (For example,
        !           130: .Fl E
        !           131: .Ar mcount
        !           132: .Fl E
        !           133: .Ar mcleanup
        !           134: is the default.)
        !           135: .Tc Fl f
        !           136: .Ws
        !           137: .Ar name
        !           138: .Cx
        !           139: prints the graph profile entry of only the specified routine
        !           140: .Ar name
        !           141: and its descendants.
        !           142: More than one
        !           143: .Fl f
        !           144: option may be given.
        !           145: Only one
        !           146: .Ar name
        !           147: may be given with each
        !           148: .Fl f
        !           149: option.
        !           150: .Tc Fl F
        !           151: .Ws
        !           152: .Ar name
        !           153: .Cx
        !           154: prints the graph profile entry of only the routine
        !           155: .Ar name
        !           156: and its descendants (as
        !           157: .Fl f ,
        !           158: above) and also uses only the times of the printed routines
        !           159: in total time and percentage computations.
        !           160: More than one
        !           161: .Fl F
        !           162: option may be given.
        !           163: Only one
        !           164: .Ar name
        !           165: may be given with each
        !           166: .Fl F
        !           167: option.
        !           168: The
        !           169: .Fl F
        !           170: option
        !           171: overrides
        !           172: the
        !           173: .Fl E
        !           174: option.
        !           175: .Tc Fl k
        !           176: .Ws
        !           177: .Ar fromname
        !           178: .Ws
        !           179: .Ar toname
        !           180: .Cx
        !           181: will delete any arcs from routine
        !           182: .Ar fromname
        !           183: to routine
        !           184: .Ar toname  .
        !           185: This can be used to break undesired cycles.
        !           186: More than one
        !           187: .Fl k
        !           188: option may be given.
        !           189: Only one pair of routine names may be given with each
        !           190: .Fl k
        !           191: option.
        !           192: .Tp Fl s
        !           193: a profile file
        !           194: .Pa gmon.sum
        !           195: is produced that represents
        !           196: the sum of the profile information in all the specified profile files.
        !           197: This summary profile file may be given to later
        !           198: executions of gprof (probably also with a
        !           199: .Fl s  )
        !           200: to accumulate profile data across several runs of an
        !           201: .Pa a.out
        !           202: file.
        !           203: .Tp Fl z
        !           204: displays routines that have zero usage (as shown by call counts
        !           205: and accumulated time).
        !           206: This is useful with the
        !           207: .Fl c
        !           208: option for discovering which routines were never called.
        !           209: .Tp
        !           210: .Sh FILES
        !           211: .Dw gmon.sum
        !           212: .Di L
        !           213: .Dp Pa a.out
        !           214: the namelist and text space.
        !           215: .Dp Pa gmon.out
        !           216: dynamic call graph and profile.
        !           217: .Dp Pa gmon.sum
        !           218: summarized dynamic call graph and profile.
        !           219: .Dp
        !           220: .Sh SEE ALSO
        !           221: .Xr monitor 3 ,
        !           222: .Xr profil 2 ,
        !           223: .Xr cc 1 ,
        !           224: .Xr prof 1
        !           225: .br
        !           226: .Em An Execution Profiler for Modular Programs ,
        !           227: by
        !           228: S. Graham, P. Kessler, M. McKusick;
        !           229: Software  - Practice and Experience,
        !           230: Vol. 13, pp. 671-685, 1983.
        !           231: .br
        !           232: .Em gprof: A Call Graph Execution Profiler ,
        !           233: by S. Graham, P. Kessler, M. McKusick;
        !           234: Proceedings of the SIGPLAN '82 Symposium on Compiler Construction,
        !           235: SIGPLAN Notices, Vol. 17, No  6, pp. 120-126, June 1982.
        !           236: .Sh HISTORY
        !           237: .Nm Gprof
        !           238: appeared in 4.2 BSD.
        !           239: .Sh BUGS
        !           240: The granularity of the sampling is shown, but remains
        !           241: statistical at best.
        !           242: We assume that the time for each execution of a function
        !           243: can be expressed by the total time for the function divided
        !           244: by the number of times the function is called.
        !           245: Thus the time propagated along the call graph arcs to the function's
        !           246: parents is directly proportional to the number of times that
        !           247: arc is traversed.
        !           248: .Pp
        !           249: Parents that are not themselves profiled will have the time of
        !           250: their profiled children propagated to them, but they will appear
        !           251: to be spontaneously invoked in the call graph listing, and will
        !           252: not have their time propagated further.
        !           253: Similarly, signal catchers, even though profiled, will appear
        !           254: to be spontaneous (although for more obscure reasons).
        !           255: Any profiled children of signal catchers should have their times
        !           256: propagated properly, unless the signal catcher was invoked during
        !           257: the execution of the profiling routine, in which case all is lost.
        !           258: .Pp
        !           259: The profiled program must call
        !           260: .Xr exit  2
        !           261: or return normally for the profiling information to be saved
        !           262: in the
        !           263: .Pa gmon.out
        !           264: file.

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