diff options
Diffstat (limited to 'upstream/opensuse-leap-15-6/man1/gprof.1')
| -rw-r--r-- | upstream/opensuse-leap-15-6/man1/gprof.1 | 698 |
1 files changed, 698 insertions, 0 deletions
diff --git a/upstream/opensuse-leap-15-6/man1/gprof.1 b/upstream/opensuse-leap-15-6/man1/gprof.1 new file mode 100644 index 00000000..da349379 --- /dev/null +++ b/upstream/opensuse-leap-15-6/man1/gprof.1 @@ -0,0 +1,698 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "GPROF 1" +.TH GPROF 1 2023-07-30 binutils-2.41 GNU +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +gprof \- display call graph profile data +.SH SYNOPSIS +.IX Header "SYNOPSIS" +gprof [ \-[abcDhilLrsTvwxyz] ] [ \-[ABCeEfFJnNOpPqQRStZ][\fIname\fR] ] + [ \-I \fIdirs\fR ] [ \-d[\fInum\fR] ] [ \-k \fIfrom/to\fR ] + [ \-m \fImin-count\fR ] [ \-R \fImap_file\fR ] [ \-t \fItable-length\fR ] + [ \-\-[no\-]annotated\-source[=\fIname\fR] ] + [ \-\-[no\-]exec\-counts[=\fIname\fR] ] + [ \-\-[no\-]flat\-profile[=\fIname\fR] ] [ \-\-[no\-]graph[=\fIname\fR] ] + [ \-\-[no\-]time=\fIname\fR] [ \-\-all\-lines ] [ \-\-brief ] + [ \-\-debug[=\fIlevel\fR] ] [ \-\-function\-ordering ] + [ \-\-file\-ordering \fImap_file\fR ] [ \-\-directory\-path=\fIdirs\fR ] + [ \-\-display\-unused\-functions ] [ \-\-file\-format=\fIname\fR ] + [ \-\-file\-info ] [ \-\-help ] [ \-\-line ] [ \-\-inline\-file\-names ] + [ \-\-min\-count=\fIn\fR ] [ \-\-no\-static ] [ \-\-print\-path ] + [ \-\-separate\-files ] [ \-\-static\-call\-graph ] [ \-\-sum ] + [ \-\-table\-length=\fIlen\fR ] [ \-\-traditional ] [ \-\-version ] + [ \-\-width=\fIn\fR ] [ \-\-ignore\-non\-functions ] + [ \-\-demangle[=\fISTYLE\fR] ] [ \-\-no\-demangle ] + [\-\-external\-symbol\-table=name] + [ \fIimage-file\fR ] [ \fIprofile-file\fR ... ] +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\f(CW\*(C`gprof\*(C'\fR produces an execution profile of C, Pascal, or Fortran77 +programs. The effect of called routines is incorporated in the profile +of each caller. The profile data is taken from the call graph profile file +(\fIgmon.out\fR default) which is created by programs +that are compiled with the \fB\-pg\fR option of +\&\f(CW\*(C`cc\*(C'\fR, \f(CW\*(C`pc\*(C'\fR, and \f(CW\*(C`f77\*(C'\fR. +The \fB\-pg\fR option also links in versions of the library routines +that are compiled for profiling. \f(CW\*(C`Gprof\*(C'\fR reads the given object +file (the default is \f(CW\*(C`a.out\*(C'\fR) and establishes the relation between +its symbol table and the call graph profile from \fIgmon.out\fR. +If more than one profile file is specified, the \f(CW\*(C`gprof\*(C'\fR +output shows the sum of the profile information in the given profile files. +.PP +\&\f(CW\*(C`Gprof\*(C'\fR calculates the amount of time spent in each routine. +Next, these times are propagated along the edges of the call graph. +Cycles are discovered, and calls into a cycle are made to share the time +of the cycle. +.PP +Several forms of output are available from the analysis. +.PP +The \fIflat profile\fR shows how much time your program spent in each function, +and how many times that function was called. If you simply want to know +which functions burn most of the cycles, it is stated concisely here. +.PP +The \fIcall graph\fR shows, for each function, which functions called it, which +other functions it called, and how many times. There is also an estimate +of how much time was spent in the subroutines of each function. This can +suggest places where you might try to eliminate function calls that use a +lot of time. +.PP +The \fIannotated source\fR listing is a copy of the program's +source code, labeled with the number of times each line of the +program was executed. +.SH OPTIONS +.IX Header "OPTIONS" +These options specify which of several output formats +\&\f(CW\*(C`gprof\*(C'\fR should produce. +.PP +Many of these options take an optional \fIsymspec\fR to specify +functions to be included or excluded. These options can be +specified multiple times, with different symspecs, to include +or exclude sets of symbols. +.PP +Specifying any of these options overrides the default (\fB\-p \-q\fR), +which prints a flat profile and call graph analysis +for all functions. +.ie n .IP """\-A[\fIsymspec\fR]""" 4 +.el .IP \f(CW\-A[\fR\f(CIsymspec\fR\f(CW]\fR 4 +.IX Item "-A[symspec]" +.PD 0 +.ie n .IP """\-\-annotated\-source[=\fIsymspec\fR]""" 4 +.el .IP \f(CW\-\-annotated\-source[=\fR\f(CIsymspec\fR\f(CW]\fR 4 +.IX Item "--annotated-source[=symspec]" +.PD +The \fB\-A\fR option causes \f(CW\*(C`gprof\*(C'\fR to print annotated source code. +If \fIsymspec\fR is specified, print output only for matching symbols. +.ie n .IP """\-b""" 4 +.el .IP \f(CW\-b\fR 4 +.IX Item "-b" +.PD 0 +.ie n .IP """\-\-brief""" 4 +.el .IP \f(CW\-\-brief\fR 4 +.IX Item "--brief" +.PD +If the \fB\-b\fR option is given, \f(CW\*(C`gprof\*(C'\fR doesn't print the +verbose blurbs that try to explain the meaning of all of the fields in +the tables. This is useful if you intend to print out the output, or +are tired of seeing the blurbs. +.ie n .IP """\-B""" 4 +.el .IP \f(CW\-B\fR 4 +.IX Item "-B" +The \fB\-B\fR option causes \f(CW\*(C`gprof\*(C'\fR to print the call graph analysis. +.ie n .IP """\-C[\fIsymspec\fR]""" 4 +.el .IP \f(CW\-C[\fR\f(CIsymspec\fR\f(CW]\fR 4 +.IX Item "-C[symspec]" +.PD 0 +.ie n .IP """\-\-exec\-counts[=\fIsymspec\fR]""" 4 +.el .IP \f(CW\-\-exec\-counts[=\fR\f(CIsymspec\fR\f(CW]\fR 4 +.IX Item "--exec-counts[=symspec]" +.PD +The \fB\-C\fR option causes \f(CW\*(C`gprof\*(C'\fR to +print a tally of functions and the number of times each was called. +If \fIsymspec\fR is specified, print tally only for matching symbols. +.Sp +If the profile data file contains basic-block count records, specifying +the \fB\-l\fR option, along with \fB\-C\fR, will cause basic-block +execution counts to be tallied and displayed. +.ie n .IP """\-i""" 4 +.el .IP \f(CW\-i\fR 4 +.IX Item "-i" +.PD 0 +.ie n .IP """\-\-file\-info""" 4 +.el .IP \f(CW\-\-file\-info\fR 4 +.IX Item "--file-info" +.PD +The \fB\-i\fR option causes \f(CW\*(C`gprof\*(C'\fR to display summary information +about the profile data file(s) and then exit. The number of histogram, +call graph, and basic-block count records is displayed. +.ie n .IP """\-I \fIdirs\fR""" 4 +.el .IP "\f(CW\-I \fR\f(CIdirs\fR\f(CW\fR" 4 +.IX Item "-I dirs" +.PD 0 +.ie n .IP """\-\-directory\-path=\fIdirs\fR""" 4 +.el .IP \f(CW\-\-directory\-path=\fR\f(CIdirs\fR\f(CW\fR 4 +.IX Item "--directory-path=dirs" +.PD +The \fB\-I\fR option specifies a list of search directories in +which to find source files. Environment variable \fIGPROF_PATH\fR +can also be used to convey this information. +Used mostly for annotated source output. +.ie n .IP """\-J[\fIsymspec\fR]""" 4 +.el .IP \f(CW\-J[\fR\f(CIsymspec\fR\f(CW]\fR 4 +.IX Item "-J[symspec]" +.PD 0 +.ie n .IP """\-\-no\-annotated\-source[=\fIsymspec\fR]""" 4 +.el .IP \f(CW\-\-no\-annotated\-source[=\fR\f(CIsymspec\fR\f(CW]\fR 4 +.IX Item "--no-annotated-source[=symspec]" +.PD +The \fB\-J\fR option causes \f(CW\*(C`gprof\*(C'\fR not to +print annotated source code. +If \fIsymspec\fR is specified, \f(CW\*(C`gprof\*(C'\fR prints annotated source, +but excludes matching symbols. +.ie n .IP """\-L""" 4 +.el .IP \f(CW\-L\fR 4 +.IX Item "-L" +.PD 0 +.ie n .IP """\-\-print\-path""" 4 +.el .IP \f(CW\-\-print\-path\fR 4 +.IX Item "--print-path" +.PD +Normally, source filenames are printed with the path +component suppressed. The \fB\-L\fR option causes \f(CW\*(C`gprof\*(C'\fR +to print the full pathname of +source filenames, which is determined +from symbolic debugging information in the image file +and is relative to the directory in which the compiler +was invoked. +.ie n .IP """\-p[\fIsymspec\fR]""" 4 +.el .IP \f(CW\-p[\fR\f(CIsymspec\fR\f(CW]\fR 4 +.IX Item "-p[symspec]" +.PD 0 +.ie n .IP """\-\-flat\-profile[=\fIsymspec\fR]""" 4 +.el .IP \f(CW\-\-flat\-profile[=\fR\f(CIsymspec\fR\f(CW]\fR 4 +.IX Item "--flat-profile[=symspec]" +.PD +The \fB\-p\fR option causes \f(CW\*(C`gprof\*(C'\fR to print a flat profile. +If \fIsymspec\fR is specified, print flat profile only for matching symbols. +.ie n .IP """\-P[\fIsymspec\fR]""" 4 +.el .IP \f(CW\-P[\fR\f(CIsymspec\fR\f(CW]\fR 4 +.IX Item "-P[symspec]" +.PD 0 +.ie n .IP """\-\-no\-flat\-profile[=\fIsymspec\fR]""" 4 +.el .IP \f(CW\-\-no\-flat\-profile[=\fR\f(CIsymspec\fR\f(CW]\fR 4 +.IX Item "--no-flat-profile[=symspec]" +.PD +The \fB\-P\fR option causes \f(CW\*(C`gprof\*(C'\fR to suppress printing a flat profile. +If \fIsymspec\fR is specified, \f(CW\*(C`gprof\*(C'\fR prints a flat profile, +but excludes matching symbols. +.ie n .IP """\-q[\fIsymspec\fR]""" 4 +.el .IP \f(CW\-q[\fR\f(CIsymspec\fR\f(CW]\fR 4 +.IX Item "-q[symspec]" +.PD 0 +.ie n .IP """\-\-graph[=\fIsymspec\fR]""" 4 +.el .IP \f(CW\-\-graph[=\fR\f(CIsymspec\fR\f(CW]\fR 4 +.IX Item "--graph[=symspec]" +.PD +The \fB\-q\fR option causes \f(CW\*(C`gprof\*(C'\fR to print the call graph analysis. +If \fIsymspec\fR is specified, print call graph only for matching symbols +and their children. +.ie n .IP """\-Q[\fIsymspec\fR]""" 4 +.el .IP \f(CW\-Q[\fR\f(CIsymspec\fR\f(CW]\fR 4 +.IX Item "-Q[symspec]" +.PD 0 +.ie n .IP """\-\-no\-graph[=\fIsymspec\fR]""" 4 +.el .IP \f(CW\-\-no\-graph[=\fR\f(CIsymspec\fR\f(CW]\fR 4 +.IX Item "--no-graph[=symspec]" +.PD +The \fB\-Q\fR option causes \f(CW\*(C`gprof\*(C'\fR to suppress printing the +call graph. +If \fIsymspec\fR is specified, \f(CW\*(C`gprof\*(C'\fR prints a call graph, +but excludes matching symbols. +.ie n .IP """\-t""" 4 +.el .IP \f(CW\-t\fR 4 +.IX Item "-t" +.PD 0 +.ie n .IP """\-\-table\-length=\fInum\fR""" 4 +.el .IP \f(CW\-\-table\-length=\fR\f(CInum\fR\f(CW\fR 4 +.IX Item "--table-length=num" +.PD +The \fB\-t\fR option causes the \fInum\fR most active source lines in +each source file to be listed when source annotation is enabled. The +default is 10. +.ie n .IP """\-y""" 4 +.el .IP \f(CW\-y\fR 4 +.IX Item "-y" +.PD 0 +.ie n .IP """\-\-separate\-files""" 4 +.el .IP \f(CW\-\-separate\-files\fR 4 +.IX Item "--separate-files" +.PD +This option affects annotated source output only. +Normally, \f(CW\*(C`gprof\*(C'\fR prints annotated source files +to standard-output. If this option is specified, +annotated source for a file named \fIpath/filename\fR +is generated in the file \fIfilename\-ann\fR. If the underlying +file system would truncate \fIfilename\-ann\fR so that it +overwrites the original \fIfilename\fR, \f(CW\*(C`gprof\*(C'\fR generates +annotated source in the file \fIfilename.ann\fR instead (if the +original file name has an extension, that extension is \fIreplaced\fR +with \fI.ann\fR). +.ie n .IP """\-Z[\fIsymspec\fR]""" 4 +.el .IP \f(CW\-Z[\fR\f(CIsymspec\fR\f(CW]\fR 4 +.IX Item "-Z[symspec]" +.PD 0 +.ie n .IP """\-\-no\-exec\-counts[=\fIsymspec\fR]""" 4 +.el .IP \f(CW\-\-no\-exec\-counts[=\fR\f(CIsymspec\fR\f(CW]\fR 4 +.IX Item "--no-exec-counts[=symspec]" +.PD +The \fB\-Z\fR option causes \f(CW\*(C`gprof\*(C'\fR not to +print a tally of functions and the number of times each was called. +If \fIsymspec\fR is specified, print tally, but exclude matching symbols. +.ie n .IP """\-r""" 4 +.el .IP \f(CW\-r\fR 4 +.IX Item "-r" +.PD 0 +.ie n .IP """\-\-function\-ordering""" 4 +.el .IP \f(CW\-\-function\-ordering\fR 4 +.IX Item "--function-ordering" +.PD +The \fB\-\-function\-ordering\fR option causes \f(CW\*(C`gprof\*(C'\fR to print a +suggested function ordering for the program based on profiling data. +This option suggests an ordering which may improve paging, tlb and +cache behavior for the program on systems which support arbitrary +ordering of functions in an executable. +.Sp +The exact details of how to force the linker to place functions +in a particular order is system dependent and out of the scope of this +manual. +.ie n .IP """\-R \fImap_file\fR""" 4 +.el .IP "\f(CW\-R \fR\f(CImap_file\fR\f(CW\fR" 4 +.IX Item "-R map_file" +.PD 0 +.ie n .IP """\-\-file\-ordering \fImap_file\fR""" 4 +.el .IP "\f(CW\-\-file\-ordering \fR\f(CImap_file\fR\f(CW\fR" 4 +.IX Item "--file-ordering map_file" +.PD +The \fB\-\-file\-ordering\fR option causes \f(CW\*(C`gprof\*(C'\fR to print a +suggested .o link line ordering for the program based on profiling data. +This option suggests an ordering which may improve paging, tlb and +cache behavior for the program on systems which do not support arbitrary +ordering of functions in an executable. +.Sp +Use of the \fB\-a\fR argument is highly recommended with this option. +.Sp +The \fImap_file\fR argument is a pathname to a file which provides +function name to object file mappings. The format of the file is similar to +the output of the program \f(CW\*(C`nm\*(C'\fR. +.Sp +.Vb 8 +\& 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 +\& ... +.Ve +.Sp +To create a \fImap_file\fR with GNU \f(CW\*(C`nm\*(C'\fR, type a command like +\&\f(CW\*(C`nm \-\-extern\-only \-\-defined\-only \-v \-\-print\-file\-name program\-name\*(C'\fR. +.ie n .IP """\-T""" 4 +.el .IP \f(CW\-T\fR 4 +.IX Item "-T" +.PD 0 +.ie n .IP """\-\-traditional""" 4 +.el .IP \f(CW\-\-traditional\fR 4 +.IX Item "--traditional" +.PD +The \fB\-T\fR option causes \f(CW\*(C`gprof\*(C'\fR to print its output in +"traditional" BSD style. +.ie n .IP """\-w \fIwidth\fR""" 4 +.el .IP "\f(CW\-w \fR\f(CIwidth\fR\f(CW\fR" 4 +.IX Item "-w width" +.PD 0 +.ie n .IP """\-\-width=\fIwidth\fR""" 4 +.el .IP \f(CW\-\-width=\fR\f(CIwidth\fR\f(CW\fR 4 +.IX Item "--width=width" +.PD +Sets width of output lines to \fIwidth\fR. +Currently only used when printing the function index at the bottom +of the call graph. +.ie n .IP """\-x""" 4 +.el .IP \f(CW\-x\fR 4 +.IX Item "-x" +.PD 0 +.ie n .IP """\-\-all\-lines""" 4 +.el .IP \f(CW\-\-all\-lines\fR 4 +.IX Item "--all-lines" +.PD +This option affects annotated source output only. +By default, only the lines at the beginning of a basic-block +are annotated. If this option is specified, every line in +a basic-block is annotated by repeating the annotation for the +first line. This behavior is similar to \f(CW\*(C`tcov\*(C'\fR's \fB\-a\fR. +.ie n .IP """\-\-demangle[=\fIstyle\fR]""" 4 +.el .IP \f(CW\-\-demangle[=\fR\f(CIstyle\fR\f(CW]\fR 4 +.IX Item "--demangle[=style]" +.PD 0 +.ie n .IP """\-\-no\-demangle""" 4 +.el .IP \f(CW\-\-no\-demangle\fR 4 +.IX Item "--no-demangle" +.PD +These options control whether C++ symbol names should be demangled when +printing output. The default is to demangle symbols. The +\&\f(CW\*(C`\-\-no\-demangle\*(C'\fR option may be used to turn off demangling. Different +compilers have different mangling styles. The optional demangling style +argument can be used to choose an appropriate demangling style for your +compiler. +.SS "Analysis Options" +.IX Subsection "Analysis Options" +.ie n .IP """\-a""" 4 +.el .IP \f(CW\-a\fR 4 +.IX Item "-a" +.PD 0 +.ie n .IP """\-\-no\-static""" 4 +.el .IP \f(CW\-\-no\-static\fR 4 +.IX Item "--no-static" +.PD +The \fB\-a\fR option causes \f(CW\*(C`gprof\*(C'\fR to suppress the printing of +statically declared (private) functions. (These are functions whose +names are not listed as global, and which are not visible outside the +file/function/block where they were defined.) Time spent in these +functions, calls to/from them, etc., will all be attributed to the +function that was loaded directly before it in the executable file. +This option affects both the flat profile and the call graph. +.ie n .IP """\-c""" 4 +.el .IP \f(CW\-c\fR 4 +.IX Item "-c" +.PD 0 +.ie n .IP """\-\-static\-call\-graph""" 4 +.el .IP \f(CW\-\-static\-call\-graph\fR 4 +.IX Item "--static-call-graph" +.PD +The \fB\-c\fR option causes the call graph of the program to be +augmented by a heuristic which examines the text space of the object +file and identifies function calls in the binary machine code. +Since normal call graph records are only generated when functions are +entered, this option identifies children that could have been called, +but never were. Calls to functions that were not compiled with +profiling enabled are also identified, but only if symbol table +entries are present for them. +Calls to dynamic library routines are typically \fInot\fR found +by this option. +Parents or children identified via this heuristic +are indicated in the call graph with call counts of \fB0\fR. +.ie n .IP """\-D""" 4 +.el .IP \f(CW\-D\fR 4 +.IX Item "-D" +.PD 0 +.ie n .IP """\-\-ignore\-non\-functions""" 4 +.el .IP \f(CW\-\-ignore\-non\-functions\fR 4 +.IX Item "--ignore-non-functions" +.PD +The \fB\-D\fR option causes \f(CW\*(C`gprof\*(C'\fR to ignore symbols which +are not known to be functions. This option will give more accurate +profile data on systems where it is supported (Solaris and HPUX for +example). +.ie n .IP """\-k \fIfrom\fR/\fIto\fR""" 4 +.el .IP "\f(CW\-k \fR\f(CIfrom\fR\f(CW/\fR\f(CIto\fR\f(CW\fR" 4 +.IX Item "-k from/to" +The \fB\-k\fR option allows you to delete from the call graph any arcs from +symbols matching symspec \fIfrom\fR to those matching symspec \fIto\fR. +.ie n .IP """\-l""" 4 +.el .IP \f(CW\-l\fR 4 +.IX Item "-l" +.PD 0 +.ie n .IP """\-\-line""" 4 +.el .IP \f(CW\-\-line\fR 4 +.IX Item "--line" +.PD +The \fB\-l\fR option enables line-by-line profiling, which causes +histogram hits to be charged to individual source code lines, +instead of functions. This feature only works with programs compiled +by older versions of the \f(CW\*(C`gcc\*(C'\fR compiler. Newer versions of +\&\f(CW\*(C`gcc\*(C'\fR are designed to work with the \f(CW\*(C`gcov\*(C'\fR tool instead. +.Sp +If the program was compiled with basic-block counting enabled, +this option will also identify how many times each line of +code was executed. +While line-by-line profiling can help isolate where in a large function +a program is spending its time, it also significantly increases +the running time of \f(CW\*(C`gprof\*(C'\fR, and magnifies statistical +inaccuracies. +.ie n .IP """\-\-inline\-file\-names""" 4 +.el .IP \f(CW\-\-inline\-file\-names\fR 4 +.IX Item "--inline-file-names" +This option causes \f(CW\*(C`gprof\*(C'\fR to print the source file after each +symbol in both the flat profile and the call graph. The full path to the +file is printed if used with the \fB\-L\fR option. +.ie n .IP """\-m \fInum\fR""" 4 +.el .IP "\f(CW\-m \fR\f(CInum\fR\f(CW\fR" 4 +.IX Item "-m num" +.PD 0 +.ie n .IP """\-\-min\-count=\fInum\fR""" 4 +.el .IP \f(CW\-\-min\-count=\fR\f(CInum\fR\f(CW\fR 4 +.IX Item "--min-count=num" +.PD +This option affects execution count output only. +Symbols that are executed less than \fInum\fR times are suppressed. +.ie n .IP """\-n\fIsymspec\fR""" 4 +.el .IP \f(CW\-n\fR\f(CIsymspec\fR\f(CW\fR 4 +.IX Item "-nsymspec" +.PD 0 +.ie n .IP """\-\-time=\fIsymspec\fR""" 4 +.el .IP \f(CW\-\-time=\fR\f(CIsymspec\fR\f(CW\fR 4 +.IX Item "--time=symspec" +.PD +The \fB\-n\fR option causes \f(CW\*(C`gprof\*(C'\fR, in its call graph analysis, +to only propagate times for symbols matching \fIsymspec\fR. +.ie n .IP """\-N\fIsymspec\fR""" 4 +.el .IP \f(CW\-N\fR\f(CIsymspec\fR\f(CW\fR 4 +.IX Item "-Nsymspec" +.PD 0 +.ie n .IP """\-\-no\-time=\fIsymspec\fR""" 4 +.el .IP \f(CW\-\-no\-time=\fR\f(CIsymspec\fR\f(CW\fR 4 +.IX Item "--no-time=symspec" +.PD +The \fB\-n\fR option causes \f(CW\*(C`gprof\*(C'\fR, in its call graph analysis, +not to propagate times for symbols matching \fIsymspec\fR. +.ie n .IP """\-S\fIfilename\fR""" 4 +.el .IP \f(CW\-S\fR\f(CIfilename\fR\f(CW\fR 4 +.IX Item "-Sfilename" +.PD 0 +.ie n .IP """\-\-external\-symbol\-table=\fIfilename\fR""" 4 +.el .IP \f(CW\-\-external\-symbol\-table=\fR\f(CIfilename\fR\f(CW\fR 4 +.IX Item "--external-symbol-table=filename" +.PD +The \fB\-S\fR option causes \f(CW\*(C`gprof\*(C'\fR to read an external symbol table +file, such as \fI/proc/kallsyms\fR, rather than read the symbol table +from the given object file (the default is \f(CW\*(C`a.out\*(C'\fR). This is useful +for profiling kernel modules. +.ie n .IP """\-z""" 4 +.el .IP \f(CW\-z\fR 4 +.IX Item "-z" +.PD 0 +.ie n .IP """\-\-display\-unused\-functions""" 4 +.el .IP \f(CW\-\-display\-unused\-functions\fR 4 +.IX Item "--display-unused-functions" +.PD +If you give the \fB\-z\fR option, \f(CW\*(C`gprof\*(C'\fR will mention all +functions in the flat profile, even those that were never called, and +that had no time spent in them. This is useful in conjunction with the +\&\fB\-c\fR option for discovering which routines were never called. +.SS "Miscellaneous Options" +.IX Subsection "Miscellaneous Options" +.ie n .IP """\-d[\fInum\fR]""" 4 +.el .IP \f(CW\-d[\fR\f(CInum\fR\f(CW]\fR 4 +.IX Item "-d[num]" +.PD 0 +.ie n .IP """\-\-debug[=\fInum\fR]""" 4 +.el .IP \f(CW\-\-debug[=\fR\f(CInum\fR\f(CW]\fR 4 +.IX Item "--debug[=num]" +.PD +The \fB\-d\fR \fInum\fR option specifies debugging options. +If \fInum\fR is not specified, enable all debugging. +.ie n .IP """\-h""" 4 +.el .IP \f(CW\-h\fR 4 +.IX Item "-h" +.PD 0 +.ie n .IP """\-\-help""" 4 +.el .IP \f(CW\-\-help\fR 4 +.IX Item "--help" +.PD +The \fB\-h\fR option prints command line usage. +.ie n .IP """\-O\fIname\fR""" 4 +.el .IP \f(CW\-O\fR\f(CIname\fR\f(CW\fR 4 +.IX Item "-Oname" +.PD 0 +.ie n .IP """\-\-file\-format=\fIname\fR""" 4 +.el .IP \f(CW\-\-file\-format=\fR\f(CIname\fR\f(CW\fR 4 +.IX Item "--file-format=name" +.PD +Selects the format of the profile data files. Recognized formats are +\&\fBauto\fR (the default), \fBbsd\fR, \fB4.4bsd\fR, \fBmagic\fR, and +\&\fBprof\fR (not yet supported). +.ie n .IP """\-s""" 4 +.el .IP \f(CW\-s\fR 4 +.IX Item "-s" +.PD 0 +.ie n .IP """\-\-sum""" 4 +.el .IP \f(CW\-\-sum\fR 4 +.IX Item "--sum" +.PD +The \fB\-s\fR option causes \f(CW\*(C`gprof\*(C'\fR to summarize the information +in the profile data files it read in, and write out a profile data +file called \fIgmon.sum\fR, which contains all the information from +the profile data files that \f(CW\*(C`gprof\*(C'\fR read in. The file \fIgmon.sum\fR +may be one of the specified input files; the effect of this is to +merge the data in the other input files into \fIgmon.sum\fR. +.Sp +Eventually you can run \f(CW\*(C`gprof\*(C'\fR again without \fB\-s\fR to analyze the +cumulative data in the file \fIgmon.sum\fR. +.ie n .IP """\-v""" 4 +.el .IP \f(CW\-v\fR 4 +.IX Item "-v" +.PD 0 +.ie n .IP """\-\-version""" 4 +.el .IP \f(CW\-\-version\fR 4 +.IX Item "--version" +.PD +The \fB\-v\fR flag causes \f(CW\*(C`gprof\*(C'\fR to print the current version +number, and then exit. +.SS "Deprecated Options" +.IX Subsection "Deprecated Options" +These options have been replaced with newer versions that use symspecs. +.ie n .IP """\-e \fIfunction_name\fR""" 4 +.el .IP "\f(CW\-e \fR\f(CIfunction_name\fR\f(CW\fR" 4 +.IX Item "-e function_name" +The \fB\-e\fR \fIfunction\fR option tells \f(CW\*(C`gprof\*(C'\fR to not print +information about the function \fIfunction_name\fR (and its +children...) in the call graph. The function will still be listed +as a child of any functions that call it, but its index number will be +shown as \fB[not printed]\fR. More than one \fB\-e\fR option may be +given; only one \fIfunction_name\fR may be indicated with each \fB\-e\fR +option. +.ie n .IP """\-E \fIfunction_name\fR""" 4 +.el .IP "\f(CW\-E \fR\f(CIfunction_name\fR\f(CW\fR" 4 +.IX Item "-E function_name" +The \f(CW\*(C`\-E \fR\f(CIfunction\fR\f(CW\*(C'\fR option works like the \f(CW\*(C`\-e\*(C'\fR option, but +time spent in the function (and children who were not called from +anywhere else), will not be used to compute the percentages-of-time for +the call graph. More than one \fB\-E\fR option may be given; only one +\&\fIfunction_name\fR may be indicated with each \fB\-E\fR option. +.ie n .IP """\-f \fIfunction_name\fR""" 4 +.el .IP "\f(CW\-f \fR\f(CIfunction_name\fR\f(CW\fR" 4 +.IX Item "-f function_name" +The \fB\-f\fR \fIfunction\fR option causes \f(CW\*(C`gprof\*(C'\fR to limit the +call graph to the function \fIfunction_name\fR and its children (and +their children...). More than one \fB\-f\fR option may be given; +only one \fIfunction_name\fR may be indicated with each \fB\-f\fR +option. +.ie n .IP """\-F \fIfunction_name\fR""" 4 +.el .IP "\f(CW\-F \fR\f(CIfunction_name\fR\f(CW\fR" 4 +.IX Item "-F function_name" +The \fB\-F\fR \fIfunction\fR option works like the \f(CW\*(C`\-f\*(C'\fR option, but +only time spent in the function and its children (and their +children...) will be used to determine total-time and +percentages-of-time for the call graph. More than one \fB\-F\fR option +may be given; only one \fIfunction_name\fR may be indicated with each +\&\fB\-F\fR option. The \fB\-F\fR option overrides the \fB\-E\fR option. +.SH FILES +.IX Header "FILES" +.ie n .IP """\fIa.out\fR""" 4 +.el .IP \f(CW\fR\f(CIa.out\fR\f(CW\fR 4 +.IX Item "a.out" +the namelist and text space. +.ie n .IP """\fIgmon.out\fR""" 4 +.el .IP \f(CW\fR\f(CIgmon.out\fR\f(CW\fR 4 +.IX Item "gmon.out" +dynamic call graph and profile. +.ie n .IP """\fIgmon.sum\fR""" 4 +.el .IP \f(CW\fR\f(CIgmon.sum\fR\f(CW\fR 4 +.IX Item "gmon.sum" +summarized dynamic call graph and profile. +.SH BUGS +.IX Header "BUGS" +The granularity of the sampling is shown, but remains +statistical at best. +We assume that the time for each execution of a function +can be expressed by the total time for the function divided +by the number of times the function is called. +Thus the time propagated along the call graph arcs to the function's +parents is directly proportional to the number of times that +arc is traversed. +.PP +Parents that are not themselves profiled will have the time of +their profiled children propagated to them, but they will appear +to be spontaneously invoked in the call graph listing, and will +not have their time propagated further. +Similarly, signal catchers, even though profiled, will appear +to be spontaneous (although for more obscure reasons). +Any profiled children of signal catchers should have their times +propagated properly, unless the signal catcher was invoked during +the execution of the profiling routine, in which case all is lost. +.PP +The profiled program must call \f(CW\*(C`exit\*(C'\fR(2) +or return normally for the profiling information to be saved +in the \fIgmon.out\fR file. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBmonitor\fR\|(3), \fBprofil\fR\|(2), \fBcc\fR\|(1), \fBprof\fR\|(1), and the Info entry for \fIgprof\fR. +.PP +"An Execution Profiler for Modular Programs", +by S. Graham, P. Kessler, M. McKusick; +Software \- Practice and Experience, +Vol. 13, pp. 671\-685, 1983. +.PP +"gprof: A Call Graph Execution Profiler", +by 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. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright (c) 1988\-2023 Free Software Foundation, Inc. +.PP +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 +or any later version published by the Free Software Foundation; +with no Invariant Sections, with no Front-Cover Texts, and with no +Back-Cover Texts. A copy of the license is included in the +section entitled "GNU Free Documentation License". |