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