Commit | Line | Data |
---|---|---|
15637ed4 RG |
1 | .\" Copyright (c) 1983, 1990 The Regents of the University of California. |
2 | .\" All rights reserved. | |
3 | .\" | |
4 | .\" Redistribution and use in source and binary forms, with or without | |
5 | .\" modification, are permitted provided that the following conditions | |
6 | .\" are met: | |
7 | .\" 1. Redistributions of source code must retain the above copyright | |
8 | .\" notice, this list of conditions and the following disclaimer. | |
9 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
10 | .\" notice, this list of conditions and the following disclaimer in the | |
11 | .\" documentation and/or other materials provided with the distribution. | |
12 | .\" 3. All advertising materials mentioning features or use of this software | |
13 | .\" must display the following acknowledgement: | |
14 | .\" This product includes software developed by the University of | |
15 | .\" California, Berkeley and its contributors. | |
16 | .\" 4. Neither the name of the University nor the names of its contributors | |
17 | .\" may be used to endorse or promote products derived from this software | |
18 | .\" without specific prior written permission. | |
19 | .\" | |
20 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
21 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
22 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
23 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
24 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
25 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
26 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
27 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
28 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
29 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
30 | .\" SUCH DAMAGE. | |
31 | .\" | |
32 | .\" @(#)gprof.1 6.8 (Berkeley) 7/24/91 | |
33 | .\" | |
34 | .Dd July 24, 1991 | |
35 | .Dt GPROF 1 | |
36 | .Os BSD 4.2 | |
37 | .Sh NAME | |
38 | .Nm gprof | |
39 | .Nd display call graph profile data | |
40 | .Sh SYNOPSIS | |
41 | .Nm gprof | |
42 | .Op options | |
43 | .Op Ar a.out Op Ar gmon.out ... | |
44 | .Sh DESCRIPTION | |
45 | .Nm Gprof | |
46 | produces an execution profile of C, Pascal, or Fortran77 programs. | |
47 | The effect of called routines is incorporated in the profile of each caller. | |
48 | The profile data is taken from the call graph profile file | |
49 | .Pf ( Pa gmon.out | |
50 | default) which is created by programs | |
51 | that are compiled with the | |
52 | .Fl pg | |
53 | option of | |
54 | .Xr cc 1 , | |
55 | .Xr pc 1 , | |
56 | and | |
57 | .Xr f77 1 . | |
58 | The | |
59 | .Fl pg | |
60 | option also links in versions of the library routines | |
61 | that are compiled for profiling. | |
62 | .Nm Gprof | |
63 | reads the given object file (the default is | |
64 | .Pa a.out) | |
65 | and establishes the relation between it's symbol table | |
66 | and the call graph profile from | |
67 | .Pa gmon.out . | |
68 | If more than one profile file is specified, | |
69 | the | |
70 | .Nm gprof | |
71 | output shows the sum of the profile information in the given profile files. | |
72 | .Pp | |
73 | .Nm Gprof | |
74 | calculates the amount of time spent in each routine. | |
75 | Next, these times are propagated along the edges of the call graph. | |
76 | Cycles are discovered, and calls into a cycle are made to share the time | |
77 | of the cycle. | |
78 | The first listing shows the functions | |
79 | sorted according to the time they represent | |
80 | including the time of their call graph descendents. | |
81 | Below each function entry is shown its (direct) call graph children, | |
82 | and how their times are propagated to this function. | |
83 | A similar display above the function shows how this function's time and the | |
84 | time of its descendents is propagated to its (direct) call graph parents. | |
85 | .Pp | |
86 | Cycles are also shown, with an entry for the cycle as a whole and | |
87 | a listing of the members of the cycle and their contributions to the | |
88 | time and call counts of the cycle. | |
89 | .Pp | |
90 | Second, a flat profile is given, | |
91 | similar to that provided by | |
92 | .Xr prof 1 . | |
93 | This listing gives the total execution times, the call counts, | |
94 | the time in milleseconds the call spent in the routine itself, and | |
95 | the time in milleseconds the call spent in the routine itself including | |
96 | its descendents. | |
97 | .Pp | |
98 | Finally, an index of the function names is provided. | |
99 | .Pp | |
100 | The following options are available: | |
101 | .Bl -tag -width Fl | |
102 | .It Fl a | |
103 | Suppresses the printing of statically declared functions. | |
104 | If this option is given, all relevant information about the static function | |
105 | (e.g., time samples, calls to other functions, calls from other functions) | |
106 | belongs to the function loaded just before the static function in the | |
107 | .Pa a.out | |
108 | file. | |
109 | .It Fl b | |
110 | Suppresses the printing of a description of each field in the profile. | |
111 | .It Fl c | |
112 | The static call graph of the program is discovered by a heuristic | |
113 | that examines the text space of the object file. | |
114 | Static-only parents or children are shown | |
115 | with call counts of 0. | |
116 | .It Fl e Ar name | |
117 | Suppresses the printing of the graph profile entry for routine | |
118 | .Ar name | |
119 | and all its descendants | |
120 | (unless they have other ancestors that aren't suppressed). | |
121 | More than one | |
122 | .Fl e | |
123 | option may be given. | |
124 | Only one | |
125 | .Ar name | |
126 | may be given with each | |
127 | .Fl e | |
128 | option. | |
129 | .It Fl E Ar name | |
130 | Suppresses the printing of the graph profile entry for routine | |
131 | .Ar name | |
132 | (and its descendants) as | |
133 | .Fl e , | |
134 | above, and also excludes the time spent in | |
135 | .Ar name | |
136 | (and its descendants) from the total and percentage time computations. | |
137 | (For example, | |
138 | .Fl E | |
139 | .Ar mcount | |
140 | .Fl E | |
141 | .Ar mcleanup | |
142 | is the default.) | |
143 | .It Fl f Ar name | |
144 | Prints the graph profile entry of only the specified routine | |
145 | .Ar name | |
146 | and its descendants. | |
147 | More than one | |
148 | .Fl f | |
149 | option may be given. | |
150 | Only one | |
151 | .Ar name | |
152 | may be given with each | |
153 | .Fl f | |
154 | option. | |
155 | .It Fl F Ar name | |
156 | Prints the graph profile entry of only the routine | |
157 | .Ar name | |
158 | and its descendants (as | |
159 | .Fl f , | |
160 | above) and also uses only the times of the printed routines | |
161 | in total time and percentage computations. | |
162 | More than one | |
163 | .Fl F | |
164 | option may be given. | |
165 | Only one | |
166 | .Ar name | |
167 | may be given with each | |
168 | .Fl F | |
169 | option. | |
170 | The | |
171 | .Fl F | |
172 | option | |
173 | overrides | |
174 | the | |
175 | .Fl E | |
176 | option. | |
177 | .It Fl k Ar fromname Ar toname | |
178 | Will delete any arcs from routine | |
179 | .Ar fromname | |
180 | to routine | |
181 | .Ar toname . | |
182 | This can be used to break undesired cycles. | |
183 | More than one | |
184 | .Fl k | |
185 | option may be given. | |
186 | Only one pair of routine names may be given with each | |
187 | .Fl k | |
188 | option. | |
189 | .It Fl s | |
190 | A profile file | |
191 | .Pa gmon.sum | |
192 | is produced that represents | |
193 | the sum of the profile information in all the specified profile files. | |
194 | This summary profile file may be given to later | |
195 | executions of gprof (probably also with a | |
196 | .Fl s ) | |
197 | to accumulate profile data across several runs of an | |
198 | .Pa a.out | |
199 | file. | |
200 | .It Fl z | |
201 | Displays routines that have zero usage (as shown by call counts | |
202 | and accumulated time). | |
203 | This is useful with the | |
204 | .Fl c | |
205 | option for discovering which routines were never called. | |
206 | .El | |
207 | .Sh FILES | |
208 | .Bl -tag -width gmon.sum -compact | |
209 | .It Pa a.out | |
210 | The namelist and text space. | |
211 | .It Pa gmon.out | |
212 | Dynamic call graph and profile. | |
213 | .It Pa gmon.sum | |
214 | Summarized dynamic call graph and profile. | |
215 | .El | |
216 | .Sh SEE ALSO | |
217 | .Xr monitor 3 , | |
218 | .Xr profil 2 , | |
219 | .Xr cc 1 , | |
220 | .Xr prof 1 | |
221 | .Rs | |
222 | .%T "An Execution Profiler for Modular Programs" | |
223 | .%A S. Graham | |
224 | .%A P. Kessler | |
225 | .%A M. McKusick | |
226 | .%J "Software - Practice and Experience" | |
227 | .%V 13 | |
228 | .%P pp. 671-685 | |
229 | .%D 1983 | |
230 | .Re | |
231 | .Rs | |
232 | .%T "gprof: A Call Graph Execution Profiler" | |
233 | .%A S. Graham | |
234 | .%A P. Kessler | |
235 | .%A M. McKusick | |
236 | .%J "Proceedings of the SIGPLAN '82 Symposium on Compiler Construction, SIGPLAN Notices" | |
237 | .%V 17 | |
238 | .%N 6 | |
239 | .%P pp. 120-126 | |
240 | .%D June 1982 | |
241 | .Re | |
242 | .Sh HISTORY | |
243 | The | |
244 | .Nm gprof | |
245 | profiler | |
246 | appeared in | |
247 | .Bx 4.2 . | |
248 | .Sh BUGS | |
249 | The granularity of the sampling is shown, but remains | |
250 | statistical at best. | |
251 | We assume that the time for each execution of a function | |
252 | can be expressed by the total time for the function divided | |
253 | by the number of times the function is called. | |
254 | Thus the time propagated along the call graph arcs to the function's | |
255 | parents is directly proportional to the number of times that | |
256 | arc is traversed. | |
257 | .Pp | |
258 | Parents that are not themselves profiled will have the time of | |
259 | their profiled children propagated to them, but they will appear | |
260 | to be spontaneously invoked in the call graph listing, and will | |
261 | not have their time propagated further. | |
262 | Similarly, signal catchers, even though profiled, will appear | |
263 | to be spontaneous (although for more obscure reasons). | |
264 | Any profiled children of signal catchers should have their times | |
265 | propagated properly, unless the signal catcher was invoked during | |
266 | the execution of the profiling routine, in which case all is lost. | |
267 | .Pp | |
268 | The profiled program must call | |
269 | .Xr exit 2 | |
270 | or return normally for the profiling information to be saved | |
271 | in the | |
272 | .Pa gmon.out | |
273 | file. |