]>
Commit | Line | Data |
---|---|---|
2adccceb MK |
1 | .\" Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com> |
2 | .\" | |
5fbde956 | 3 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
2adccceb | 4 | .\" |
a5ebdc8d | 5 | .TH sprof 1 (date) "Linux man-pages (unreleased)" |
2adccceb MK |
6 | .SH NAME |
7 | sprof \- read and display shared object profiling data | |
8 | .SH SYNOPSIS | |
9 | .nf | |
4c9b3247 MK |
10 | .BR sprof " [\fIoption\fP]... \fIshared-object-path\fP \ |
11 | [\fIprofile-data-path\fP]" | |
2adccceb MK |
12 | .fi |
13 | .SH DESCRIPTION | |
14 | The | |
15 | .B sprof | |
16 | command displays a profiling summary for the | |
43151de3 | 17 | shared object (shared library) specified as its first command-line argument. |
2adccceb MK |
18 | The profiling summary is created using previously generated |
19 | profiling data in the (optional) second command-line argument. | |
20 | If the profiling data pathname is omitted, then | |
21 | .B sprof | |
22 | will attempt to deduce it using the soname of the shared object, | |
23 | looking for a file with the name | |
a28b73cd | 24 | .I <soname>.profile |
2adccceb MK |
25 | in the current directory. |
26 | .SH OPTIONS | |
27 | The following command-line options specify the profile output | |
28 | to be produced: | |
29 | .TP | |
6fdb1c03 | 30 | .B \-\-call\-pairs |
5a3a191d AC |
31 | .TQ |
32 | .B \-c | |
2adccceb MK |
33 | Print a list of pairs of call paths for the interfaces exported |
34 | by the shared object, | |
35 | along with the number of times each path is used. | |
36 | .TP | |
6fdb1c03 | 37 | .B \-\-flat\-profile |
5a3a191d AC |
38 | .TQ |
39 | .B \-p | |
2adccceb MK |
40 | Generate a flat profile of all of the functions in the monitored object, |
41 | with counts and ticks. | |
42 | .TP | |
6fdb1c03 | 43 | .B \-\-graph |
5a3a191d AC |
44 | .TQ |
45 | .B \-q | |
2adccceb MK |
46 | Generate a call graph. |
47 | .PP | |
48 | If none of the above options is specified, | |
49 | then the default behavior is to display a flat profile and a call graph. | |
50 | .PP | |
51 | The following additional command-line options are available: | |
52 | .TP | |
6fdb1c03 | 53 | .B \-\-help |
5a3a191d AC |
54 | .TQ |
55 | .B \-? | |
2adccceb MK |
56 | Display a summary of command-line options and arguments and exit. |
57 | .TP | |
a28b73cd | 58 | .B \-\-usage |
2adccceb MK |
59 | Display a short usage message and exit. |
60 | .TP | |
6fdb1c03 | 61 | .B \-\-version |
5a3a191d AC |
62 | .TQ |
63 | .B \-V | |
2adccceb | 64 | Display the program version and exit. |
3113c7f3 | 65 | .SH STANDARDS |
4131356c | 66 | GNU. |
a14af333 | 67 | .SH EXAMPLES |
2adccceb MK |
68 | The following example demonstrates the use of |
69 | .BR sprof . | |
70 | The example consists of a main program that calls two functions | |
43151de3 | 71 | in a shared object. |
2adccceb | 72 | First, the code of the main program: |
2a86152e | 73 | .PP |
2adccceb | 74 | .in +4n |
60d3774e | 75 | .EX |
2adccceb MK |
76 | $ \fBcat prog.c\fP |
77 | #include <stdlib.h> | |
fe5dba13 | 78 | \& |
2adccceb MK |
79 | void x1(void); |
80 | void x2(void); | |
fe5dba13 | 81 | \& |
2adccceb MK |
82 | int |
83 | main(int argc, char *argv[]) | |
84 | { | |
85 | x1(); | |
86 | x2(); | |
87 | exit(EXIT_SUCCESS); | |
88 | } | |
60d3774e | 89 | .EE |
2adccceb MK |
90 | .in |
91 | .PP | |
92 | The functions | |
a28b73cd | 93 | .IR x1 () |
2adccceb | 94 | and |
a28b73cd | 95 | .IR x2 () |
2adccceb | 96 | are defined in the following source file that is used to |
43151de3 | 97 | construct the shared object: |
2a86152e | 98 | .PP |
2adccceb | 99 | .in +4n |
60d3774e | 100 | .EX |
2adccceb MK |
101 | $ \fBcat libdemo.c\fP |
102 | #include <unistd.h> | |
fe5dba13 | 103 | \& |
2adccceb MK |
104 | void |
105 | consumeCpu1(int lim) | |
106 | { | |
b42296e4 | 107 | for (unsigned int j = 0; j < lim; j++) |
2adccceb MK |
108 | getppid(); |
109 | } | |
fe5dba13 | 110 | \& |
2adccceb MK |
111 | void |
112 | x1(void) { | |
b42296e4 | 113 | for (unsigned int j = 0; j < 100; j++) |
2adccceb MK |
114 | consumeCpu1(200000); |
115 | } | |
fe5dba13 | 116 | \& |
2adccceb MK |
117 | void |
118 | consumeCpu2(int lim) | |
119 | { | |
b42296e4 | 120 | for (unsigned int j = 0; j < lim; j++) |
2adccceb MK |
121 | getppid(); |
122 | } | |
fe5dba13 | 123 | \& |
2adccceb MK |
124 | void |
125 | x2(void) | |
126 | { | |
b42296e4 | 127 | for (unsigned int j = 0; j < 1000; j++) |
2adccceb MK |
128 | consumeCpu2(10000); |
129 | } | |
60d3774e | 130 | .EE |
2adccceb MK |
131 | .in |
132 | .PP | |
43151de3 | 133 | Now we construct the shared object with the real name |
2adccceb MK |
134 | .IR libdemo.so.1.0.1 , |
135 | and the soname | |
136 | .IR libdemo.so.1 : | |
2a86152e | 137 | .PP |
2adccceb | 138 | .in +4n |
60d3774e | 139 | .EX |
2adccceb MK |
140 | $ \fBcc \-g \-fPIC \-shared \-Wl,\-soname,libdemo.so.1 \e\fP |
141 | \fB\-o libdemo.so.1.0.1 libdemo.c\fP | |
60d3774e | 142 | .EE |
2adccceb MK |
143 | .in |
144 | .PP | |
145 | Then we construct symbolic links for the library soname and | |
146 | the library linker name: | |
2a86152e | 147 | .PP |
2adccceb | 148 | .in +4n |
60d3774e | 149 | .EX |
2adccceb MK |
150 | $ \fBln \-sf libdemo.so.1.0.1 libdemo.so.1\fP |
151 | $ \fBln \-sf libdemo.so.1 libdemo.so\fP | |
60d3774e | 152 | .EE |
2adccceb MK |
153 | .in |
154 | .PP | |
43151de3 | 155 | Next, we compile the main program, linking it against the shared object, |
2adccceb | 156 | and then list the dynamic dependencies of the program: |
2a86152e | 157 | .PP |
2adccceb | 158 | .in +4n |
60d3774e | 159 | .EX |
2adccceb MK |
160 | $ \fBcc \-g \-o prog prog.c \-L. \-ldemo\fP |
161 | $ \fBldd prog\fP | |
162 | linux\-vdso.so.1 => (0x00007fff86d66000) | |
163 | libdemo.so.1 => not found | |
164 | libc.so.6 => /lib64/libc.so.6 (0x00007fd4dc138000) | |
165 | /lib64/ld\-linux\-x86\-64.so.2 (0x00007fd4dc51f000) | |
60d3774e | 166 | .EE |
2adccceb MK |
167 | .in |
168 | .PP | |
43151de3 | 169 | In order to get profiling information for the shared object, |
2adccceb | 170 | we define the environment variable |
a28b73cd | 171 | .B LD_PROFILE |
2adccceb | 172 | with the soname of the library: |
2a86152e | 173 | .PP |
2adccceb | 174 | .in +4n |
60d3774e | 175 | .EX |
2adccceb | 176 | $ \fBexport LD_PROFILE=libdemo.so.1\fP |
60d3774e | 177 | .EE |
2adccceb MK |
178 | .in |
179 | .PP | |
180 | We then define the environment variable | |
a28b73cd | 181 | .B LD_PROFILE_OUTPUT |
2adccceb MK |
182 | with the pathname of the directory where profile output should be written, |
183 | and create that directory if it does not exist already: | |
2a86152e | 184 | .PP |
2adccceb | 185 | .in +4n |
60d3774e | 186 | .EX |
2adccceb MK |
187 | $ \fBexport LD_PROFILE_OUTPUT=$(pwd)/prof_data\fP |
188 | $ \fBmkdir \-p $LD_PROFILE_OUTPUT\fP | |
60d3774e | 189 | .EE |
2adccceb MK |
190 | .in |
191 | .PP | |
192 | .B LD_PROFILE | |
193 | causes profiling output to be | |
194 | .I appended | |
195 | to the output file if it already exists, | |
196 | so we ensure that there is no preexisting profiling data: | |
2a86152e | 197 | .PP |
2adccceb | 198 | .in +4n |
60d3774e | 199 | .EX |
2adccceb | 200 | $ \fBrm \-f $LD_PROFILE_OUTPUT/$LD_PROFILE.profile\fP |
60d3774e | 201 | .EE |
2adccceb MK |
202 | .in |
203 | .PP | |
204 | We then run the program to produce the profiling output, | |
205 | which is written to a file in the directory specified in | |
206 | .BR LD_PROFILE_OUTPUT : | |
2a86152e | 207 | .PP |
2adccceb | 208 | .in +4n |
60d3774e | 209 | .EX |
2adccceb MK |
210 | $ \fBLD_LIBRARY_PATH=. ./prog\fP |
211 | $ \fBls prof_data\fP | |
212 | libdemo.so.1.profile | |
60d3774e | 213 | .EE |
2adccceb MK |
214 | .in |
215 | .PP | |
216 | We then use the | |
a28b73cd | 217 | .B sprof \-p |
2adccceb | 218 | option to generate a flat profile with counts and ticks: |
2a86152e | 219 | .PP |
2adccceb | 220 | .in +4n |
60d3774e | 221 | .EX |
2adccceb MK |
222 | $ \fBsprof \-p libdemo.so.1 $LD_PROFILE_OUTPUT/libdemo.so.1.profile\fP |
223 | Flat profile: | |
fe5dba13 | 224 | \& |
2adccceb MK |
225 | Each sample counts as 0.01 seconds. |
226 | % cumulative self self total | |
227 | time seconds seconds calls us/call us/call name | |
228 | 60.00 0.06 0.06 100 600.00 consumeCpu1 | |
229 | 40.00 0.10 0.04 1000 40.00 consumeCpu2 | |
230 | 0.00 0.10 0.00 1 0.00 x1 | |
231 | 0.00 0.10 0.00 1 0.00 x2 | |
60d3774e | 232 | .EE |
2adccceb MK |
233 | .in |
234 | .PP | |
235 | The | |
a28b73cd | 236 | .B sprof \-q |
2adccceb | 237 | option generates a call graph: |
2a86152e | 238 | .PP |
2adccceb | 239 | .in +4n |
60d3774e | 240 | .EX |
2adccceb | 241 | $ \fBsprof \-q libdemo.so.1 $LD_PROFILE_OUTPUT/libdemo.so.1.profile\fP |
fe5dba13 | 242 | \& |
2adccceb | 243 | index % time self children called name |
fe5dba13 | 244 | \& |
2adccceb MK |
245 | 0.00 0.00 100/100 x1 [1] |
246 | [0] 100.0 0.00 0.00 100 consumeCpu1 [0] | |
247 | \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- | |
248 | 0.00 0.00 1/1 <UNKNOWN> | |
249 | [1] 0.0 0.00 0.00 1 x1 [1] | |
250 | 0.00 0.00 100/100 consumeCpu1 [0] | |
251 | \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- | |
252 | 0.00 0.00 1000/1000 x2 [3] | |
253 | [2] 0.0 0.00 0.00 1000 consumeCpu2 [2] | |
254 | \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- | |
255 | 0.00 0.00 1/1 <UNKNOWN> | |
256 | [3] 0.0 0.00 0.00 1 x2 [3] | |
257 | 0.00 0.00 1000/1000 consumeCpu2 [2] | |
258 | \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- | |
60d3774e | 259 | .EE |
2adccceb MK |
260 | .in |
261 | .PP | |
262 | Above and below, the "<UNKNOWN>" strings represent identifiers that | |
263 | are outside of the profiled object (in this example, these are instances of | |
264 | .IR main() ). | |
265 | .PP | |
266 | The | |
a28b73cd | 267 | .B sprof \-c |
2adccceb | 268 | option generates a list of call pairs and the number of their occurrences: |
2a86152e | 269 | .PP |
2adccceb | 270 | .in +4n |
60d3774e | 271 | .EX |
2adccceb MK |
272 | $ \fBsprof \-c libdemo.so.1 $LD_PROFILE_OUTPUT/libdemo.so.1.profile\fP |
273 | <UNKNOWN> x1 1 | |
274 | x1 consumeCpu1 100 | |
275 | <UNKNOWN> x2 1 | |
276 | x2 consumeCpu2 1000 | |
60d3774e | 277 | .EE |
2adccceb MK |
278 | .in |
279 | .SH SEE ALSO | |
280 | .BR gprof (1), | |
281 | .BR ldd (1), | |
282 | .BR ld.so (8) |