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