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