| 1 | Sun Feb 5 16:09:16 1995
|
|---|
| 2 |
|
|---|
| 3 | This file documents the changes and new features available with this
|
|---|
| 4 | version of GNU gprof.
|
|---|
| 5 |
|
|---|
| 6 | * New Features
|
|---|
| 7 |
|
|---|
| 8 | o Long options
|
|---|
| 9 |
|
|---|
| 10 | o Supports generalized file format, without breaking backward compatibility:
|
|---|
| 11 | new file format supports basic-block execution counts and non-realtime
|
|---|
| 12 | histograms (see below)
|
|---|
| 13 |
|
|---|
| 14 | o Supports profiling at the line level: flat profiles, call-graph profiles,
|
|---|
| 15 | and execution-counts can all be displayed at a level that identifies
|
|---|
| 16 | individual lines rather than just functions
|
|---|
| 17 |
|
|---|
| 18 | o Test-coverage support (similar to Sun tcov program): source files
|
|---|
| 19 | can be annotated with the number of times a function was invoked
|
|---|
| 20 | or with the number of times each basic-block in a function was
|
|---|
| 21 | executed
|
|---|
| 22 |
|
|---|
| 23 | o Generalized histograms: not just execution-time, but arbitrary
|
|---|
| 24 | histograms are support (for example, performance counter based
|
|---|
| 25 | profiles)
|
|---|
| 26 |
|
|---|
| 27 | o Powerful mechanism to select data to be included/excluded from
|
|---|
| 28 | analysis and/or output
|
|---|
| 29 |
|
|---|
| 30 | o Support for DEC OSF/1 v3.0
|
|---|
| 31 |
|
|---|
| 32 | o Full cross-platform profiling support: gprof uses BFD to support
|
|---|
| 33 | arbitrary, non-native object file formats and non-native byte-orders
|
|---|
| 34 | (this feature has not been tested yet)
|
|---|
| 35 |
|
|---|
| 36 | o In the call-graph function index, static function names are now
|
|---|
| 37 | printed together with the filename in which the function was defined
|
|---|
| 38 | (required bfd_find_nearest_line() support and symbolic debugging
|
|---|
| 39 | information to be present in the executable file)
|
|---|
| 40 |
|
|---|
| 41 | o Major overhaul of source code (compiles cleanly with -Wall, etc.)
|
|---|
| 42 |
|
|---|
| 43 | * Supported Platforms
|
|---|
| 44 |
|
|---|
| 45 | The current version is known to work on:
|
|---|
| 46 |
|
|---|
| 47 | o DEC OSF/1 v3.0
|
|---|
| 48 | All features supported.
|
|---|
| 49 |
|
|---|
| 50 | o SunOS 4.1.x
|
|---|
| 51 | All features supported.
|
|---|
| 52 |
|
|---|
| 53 | o Solaris 2.3
|
|---|
| 54 | Line-level profiling unsupported because bfd_find_nearest_line()
|
|---|
| 55 | is not fully implemented for Elf binaries.
|
|---|
| 56 |
|
|---|
| 57 | o HP-UX 9.01
|
|---|
| 58 | Line-level profiling unsupported because bfd_find_nearest_line()
|
|---|
| 59 | is not fully implemented for SOM binaries.
|
|---|
| 60 |
|
|---|
| 61 | * Detailed Description
|
|---|
| 62 |
|
|---|
| 63 | ** User Interface Changes
|
|---|
| 64 |
|
|---|
| 65 | The command-line interface is backwards compatible with earlier
|
|---|
| 66 | versions of GNU gprof and Berkeley gprof. The only exception is
|
|---|
| 67 | the option to delete arcs from the call graph. The old syntax
|
|---|
| 68 | was:
|
|---|
| 69 |
|
|---|
| 70 | -k fromname toname
|
|---|
| 71 |
|
|---|
| 72 | while the new syntax is:
|
|---|
| 73 |
|
|---|
| 74 | -k fromname/toname
|
|---|
| 75 |
|
|---|
| 76 | This change was necessary to be compatible with long-option parsing.
|
|---|
| 77 | Also, "fromname" and "toname" can now be arbitrary symspecs rather
|
|---|
| 78 | than just function names (see below for an explanation of symspecs).
|
|---|
| 79 | For example, option "-k gprof.c/" suppresses all arcs due to calls out
|
|---|
| 80 | of file "gprof.c".
|
|---|
| 81 |
|
|---|
| 82 | *** Sym Specs
|
|---|
| 83 |
|
|---|
| 84 | It is often necessary to apply gprof only to specific parts of a
|
|---|
| 85 | program. GNU gprof has a simple but powerful mechanism to achieve
|
|---|
| 86 | this. So called {\em symspecs\/} provide the foundation for this
|
|---|
| 87 | mechanism. A symspec selects the parts of a profiled program to which
|
|---|
| 88 | an operation should be applied to. The syntax of a symspec is
|
|---|
| 89 | simple:
|
|---|
| 90 |
|
|---|
| 91 | filename_containing_a_dot
|
|---|
| 92 | | funcname_not_containing_a_dot
|
|---|
| 93 | | linenumber
|
|---|
| 94 | | ( [ any_filename ] `:' ( any_funcname | linenumber ) )
|
|---|
| 95 |
|
|---|
| 96 | Here are some examples:
|
|---|
| 97 |
|
|---|
| 98 | main.c Selects everything in file "main.c"---the
|
|---|
| 99 | dot in the string tells gprof to interpret
|
|---|
| 100 | the string as a filename, rather than as
|
|---|
| 101 | a function name. To select a file whose
|
|---|
| 102 | name does contain a dot, a trailing colon
|
|---|
| 103 | should be specified. For example, "odd:" is
|
|---|
| 104 | interpreted as the file named "odd".
|
|---|
| 105 |
|
|---|
| 106 | main Selects all functions named "main". Notice
|
|---|
| 107 | that there may be multiple instances of the
|
|---|
| 108 | same function name because some of the
|
|---|
| 109 | definitions may be local (i.e., static).
|
|---|
| 110 | Unless a function name is unique in a program,
|
|---|
| 111 | you must use the colon notation explained
|
|---|
| 112 | below to specify a function from a specific
|
|---|
| 113 | source file. Sometimes, functionnames contain
|
|---|
| 114 | dots. In such cases, it is necessar to
|
|---|
| 115 | add a leading colon to the name. For example,
|
|---|
| 116 | ":.mul" selects function ".mul".
|
|---|
| 117 |
|
|---|
| 118 | main.c:main Selects function "main" in file "main.c".
|
|---|
| 119 |
|
|---|
| 120 | main.c:134 Selects line 134 in file "main.c".
|
|---|
| 121 |
|
|---|
| 122 | IMPLEMENTATION NOTE: The source code uses the type sym_id for symspecs.
|
|---|
| 123 | At some point, this probably ought to be changed to "sym_spec" to make
|
|---|
| 124 | reading the code easier.
|
|---|
| 125 |
|
|---|
| 126 | *** Long options
|
|---|
| 127 |
|
|---|
| 128 | GNU gprof now supports long options. The following is a list of all
|
|---|
| 129 | supported options. Options that are listed without description
|
|---|
| 130 | operate in the same manner as the corresponding option in older
|
|---|
| 131 | versions of gprof.
|
|---|
| 132 |
|
|---|
| 133 | Short Form: Long Form:
|
|---|
| 134 | ----------- ----------
|
|---|
| 135 | -l --line
|
|---|
| 136 | Request profiling at the line-level rather
|
|---|
| 137 | than just at the function level. Source
|
|---|
| 138 | lines are identified by symbols of the form:
|
|---|
| 139 |
|
|---|
| 140 | func (file:line)
|
|---|
| 141 |
|
|---|
| 142 | where "func" is the function name, "file" is the
|
|---|
| 143 | file name and "line" is the line-number that
|
|---|
| 144 | corresponds to the line.
|
|---|
| 145 |
|
|---|
| 146 | To work properly, the binary must contain symbolic
|
|---|
| 147 | debugging information. This means that the source
|
|---|
| 148 | have to be translated with option "-g" specified.
|
|---|
| 149 | Functions for which there is no symbolic debugging
|
|---|
| 150 | information available are treated as if "--line"
|
|---|
| 151 | had not been specified. However, the line number
|
|---|
| 152 | printed with such symbols is usually incorrect
|
|---|
| 153 | and should be ignored.
|
|---|
| 154 |
|
|---|
| 155 | -a --no-static
|
|---|
| 156 | -A[symspec] --annotated-source[=symspec]
|
|---|
| 157 | Request output in the form of annotated source
|
|---|
| 158 | files. If "symspec" is specified, print output only
|
|---|
| 159 | for symbols selected by "symspec". If the option
|
|---|
| 160 | is specified multiple times, annotated output is
|
|---|
| 161 | generated for the union of all symspecs.
|
|---|
| 162 |
|
|---|
| 163 | Examples:
|
|---|
| 164 |
|
|---|
| 165 | -A Prints annotated source for all
|
|---|
| 166 | source files.
|
|---|
| 167 | -Agprof.c Prints annotated source for file
|
|---|
| 168 | gprof.c.
|
|---|
| 169 | -Afoobar Prints annotated source for files
|
|---|
| 170 | containing a function named "foobar".
|
|---|
| 171 | The entire file will be printed, but
|
|---|
| 172 | only the function itself will be
|
|---|
| 173 | annotated with profile data.
|
|---|
| 174 |
|
|---|
| 175 | -J[symspec] --no-annotated-source[=symspec]
|
|---|
| 176 | Suppress annotated source output. If specified
|
|---|
| 177 | without argument, annotated output is suppressed
|
|---|
| 178 | completely. With an argument, annotated output
|
|---|
| 179 | is suppressed only for the symbols selected by
|
|---|
| 180 | "symspec". If the option is specified multiple
|
|---|
| 181 | times, annotated output is suppressed for the
|
|---|
| 182 | union of all symspecs. This option has lower
|
|---|
| 183 | precedence than --annotated-source
|
|---|
| 184 |
|
|---|
| 185 | -p[symspec] --flat-profile[=symspec]
|
|---|
| 186 | Request output in the form of a flat profile
|
|---|
| 187 | (unless any other output-style option is specified,
|
|---|
| 188 | this option is turned on by default). If
|
|---|
| 189 | "symspec" is specified, include only symbols
|
|---|
| 190 | selected by "symspec" in flat profile. If the
|
|---|
| 191 | option is specified multiple times, the flat
|
|---|
| 192 | profile includes symbols selected by the union
|
|---|
| 193 | of all symspecs.
|
|---|
| 194 |
|
|---|
| 195 | -P[symspec] --no-flat-profile[=symspec]
|
|---|
| 196 | Suppress output in the flat profile. If given
|
|---|
| 197 | without an argument, the flat profile is suppressed
|
|---|
| 198 | completely. If "symspec" is specified, suppress
|
|---|
| 199 | the selected symbols in the flat profile. If the
|
|---|
| 200 | option is specified multiple times, the union of
|
|---|
| 201 | the selected symbols is suppressed. This option
|
|---|
| 202 | has lower precedence than --flat-profile.
|
|---|
| 203 |
|
|---|
| 204 | -q[symspec] --graph[=symspec]
|
|---|
| 205 | Request output in the form of a call-graph
|
|---|
| 206 | (unless any other output-style option is specified,
|
|---|
| 207 | this option is turned on by default). If "symspec"
|
|---|
| 208 | is specified, include only symbols selected by
|
|---|
| 209 | "symspec" in the call-graph. If the option is
|
|---|
| 210 | specified multiple times, the call-graph includes
|
|---|
| 211 | symbols selected by the union of all symspecs.
|
|---|
| 212 |
|
|---|
| 213 | -Q[symspec] --no-graph[=symspec]
|
|---|
| 214 | Suppress output in the call-graph. If given without
|
|---|
| 215 | an argument, the call-graph is suppressed completely.
|
|---|
| 216 | With a "symspec", suppress the selected symbols
|
|---|
| 217 | from the call-graph. If the option is specified
|
|---|
| 218 | multiple times, the union of the selected symbols
|
|---|
| 219 | is suppressed. This option has lower precedence
|
|---|
| 220 | than --graph.
|
|---|
| 221 |
|
|---|
| 222 | -C[symspec] --exec-counts[=symspec]
|
|---|
| 223 | Request output in the form of execution counts.
|
|---|
| 224 | If "symspec" is present, include only symbols
|
|---|
| 225 | selected by "symspec" in the execution count
|
|---|
| 226 | listing. If the option is specified multiple
|
|---|
| 227 | times, the execution count listing includes
|
|---|
| 228 | symbols selected by the union of all symspecs.
|
|---|
| 229 |
|
|---|
| 230 | -Z[symspec] --no-exec-counts[=symspec]
|
|---|
| 231 | Suppress output in the execution count listing.
|
|---|
| 232 | If given without an argument, the listing is
|
|---|
| 233 | suppressed completely. With a "symspec", suppress
|
|---|
| 234 | the selected symbols from the call-graph. If the
|
|---|
| 235 | option is specified multiple times, the union of
|
|---|
| 236 | the selected symbols is suppressed. This option
|
|---|
| 237 | has lower precedence than --exec-counts.
|
|---|
| 238 |
|
|---|
| 239 | -i --file-info
|
|---|
| 240 | Print information about the profile files that
|
|---|
| 241 | are read. The information consists of the
|
|---|
| 242 | number and types of records present in the
|
|---|
| 243 | profile file. Currently, a profile file can
|
|---|
| 244 | contain any number and any combination of histogram,
|
|---|
| 245 | call-graph, or basic-block count records.
|
|---|
| 246 |
|
|---|
| 247 | -s --sum
|
|---|
| 248 |
|
|---|
| 249 | -x --all-lines
|
|---|
| 250 | This option affects annotated source output only.
|
|---|
| 251 | By default, only the lines at the beginning of
|
|---|
| 252 | a basic-block are annotated. If this option is
|
|---|
| 253 | specified, every line in a basic-block is annotated
|
|---|
| 254 | by repeating the annotation for the first line.
|
|---|
| 255 | This option is identical to tcov's "-a".
|
|---|
| 256 |
|
|---|
| 257 | -I dirs --directory-path=dirs
|
|---|
| 258 | This option affects annotated source output only.
|
|---|
| 259 | Specifies the list of directories to be searched
|
|---|
| 260 | for source files. The argument "dirs" is a colon
|
|---|
| 261 | separated list of directories. By default, gprof
|
|---|
| 262 | searches for source files relative to the current
|
|---|
| 263 | working directory only.
|
|---|
| 264 |
|
|---|
| 265 | -z --display-unused-functions
|
|---|
| 266 |
|
|---|
| 267 | -m num --min-count=num
|
|---|
| 268 | This option affects annotated source and execution
|
|---|
| 269 | count output only. Symbols that are executed
|
|---|
| 270 | less than "num" times are suppressed. For annotated
|
|---|
| 271 | source output, suppressed symbols are marked
|
|---|
| 272 | by five hash-marks (#####). In an execution count
|
|---|
| 273 | output, suppressed symbols do not appear at all.
|
|---|
| 274 |
|
|---|
| 275 | -L --print-path
|
|---|
| 276 | Normally, source filenames are printed with the path
|
|---|
| 277 | component suppressed. With this option, gprof
|
|---|
| 278 | can be forced to print the full pathname of
|
|---|
| 279 | source filenames. The full pathname is determined
|
|---|
| 280 | from symbolic debugging information in the image file
|
|---|
| 281 | and is relative to the directory in which the compiler
|
|---|
| 282 | was invoked.
|
|---|
| 283 |
|
|---|
| 284 | -y --separate-files
|
|---|
| 285 | This option affects annotated source output only.
|
|---|
| 286 | Normally, gprof prints annotated source files
|
|---|
| 287 | to standard-output. If this option is specified,
|
|---|
| 288 | annotated source for a file named "path/filename"
|
|---|
| 289 | is generated in the file "filename-ann". That is,
|
|---|
| 290 | annotated output is {\em always\/} generated in
|
|---|
| 291 | gprof's current working directory. Care has to
|
|---|
| 292 | be taken if a program consists of files that have
|
|---|
| 293 | identical filenames, but distinct paths.
|
|---|
| 294 |
|
|---|
| 295 | -c --static-call-graph
|
|---|
| 296 |
|
|---|
| 297 | -t num --table-length=num
|
|---|
| 298 | This option affects annotated source output only.
|
|---|
| 299 | After annotating a source file, gprof generates
|
|---|
| 300 | an execution count summary consisting of a table
|
|---|
| 301 | of lines with the top execution counts. By
|
|---|
| 302 | default, this table is ten entries long.
|
|---|
| 303 | This option can be used to change the table length
|
|---|
| 304 | or, by specifying an argument value of 0, it can be
|
|---|
| 305 | suppressed completely.
|
|---|
| 306 |
|
|---|
| 307 | -n symspec --time=symspec
|
|---|
| 308 | Only symbols selected by "symspec" are considered
|
|---|
| 309 | in total and percentage time computations.
|
|---|
| 310 | However, this option does not affect percentage time
|
|---|
| 311 | computation for the flat profile.
|
|---|
| 312 | If the option is specified multiple times, the union
|
|---|
| 313 | of all selected symbols is used in time computations.
|
|---|
| 314 |
|
|---|
| 315 | -N --no-time=symspec
|
|---|
| 316 | Exclude the symbols selected by "symspec" from
|
|---|
| 317 | total and percentage time computations.
|
|---|
| 318 | However, this option does not affect percentage time
|
|---|
| 319 | computation for the flat profile.
|
|---|
| 320 | This option is ignored if any --time options are
|
|---|
| 321 | specified.
|
|---|
| 322 |
|
|---|
| 323 | -w num --width=num
|
|---|
| 324 | Sets the output line width. Currently, this option
|
|---|
| 325 | affects the printing of the call-graph function index
|
|---|
| 326 | only.
|
|---|
| 327 |
|
|---|
| 328 | -e <no long form---for backwards compatibility only>
|
|---|
|
|---|
