Debian Codegraph @

upstream/debian-trixie/man1/sprof.1

raw
1 .\" Copyright (C) 2014 Michael Kerrisk <[email protected]>
2 .\"
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
4 .\"
5 .TH sprof 1 2024-06-15 "Linux man-pages 6.9.1"
6 .SH NAME
7 sprof \- read and display shared object profiling data
8 .SH SYNOPSIS
9 .nf
10 .BR sprof " [\fIoption\fP]... \fIshared-object-path\fP \
11 [\fIprofile-data-path\fP]"
12 .fi
13 .SH DESCRIPTION
14 The
15 .B sprof
16 command displays a profiling summary for the
17 shared object (shared library) specified as its first command-line argument.
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
24 .I <soname>.profile
25 in the current directory.
26 .SH OPTIONS
27 The following command-line options specify the profile output
28 to be produced:
29 .TP
30 .B \-\-call\-pairs
31 .TQ
32 .B \-c
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
37 .B \-\-flat\-profile
38 .TQ
39 .B \-p
40 Generate a flat profile of all of the functions in the monitored object,
41 with counts and ticks.
42 .TP
43 .B \-\-graph
44 .TQ
45 .B \-q
46 Generate a call graph.
47 .P
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 .P
51 The following additional command-line options are available:
52 .TP
53 .B \-\-help
54 .TQ
55 .B \-?
56 Display a summary of command-line options and arguments and exit.
57 .TP
58 .B \-\-usage
59 Display a short usage message and exit.
60 .TP
61 .B \-\-version
62 .TQ
63 .B \-V
64 Display the program version and exit.
65 .SH STANDARDS
66 GNU.
67 .SH EXAMPLES
68 The following example demonstrates the use of
69 .BR sprof .
70 The example consists of a main program that calls two functions
71 in a shared object.
72 First, the code of the main program:
73 .P
74 .in +4n
75 .EX
76 $ \fBcat prog.c\fP
77 #include <stdlib.h>
78 \&
79 void x1(void);
80 void x2(void);
81 \&
82 int
83 main(int argc, char *argv[])
84 {
85 x1();
86 x2();
87 exit(EXIT_SUCCESS);
88 }
89 .EE
90 .in
91 .P
92 The functions
93 .IR x1 ()
94 and
95 .IR x2 ()
96 are defined in the following source file that is used to
97 construct the shared object:
98 .P
99 .in +4n
100 .EX
101 $ \fBcat libdemo.c\fP
102 #include <unistd.h>
103 \&
104 void
105 consumeCpu1(int lim)
106 {
107 for (unsigned int j = 0; j < lim; j++)
108 getppid();
109 }
110 \&
111 void
112 x1(void) {
113 for (unsigned int j = 0; j < 100; j++)
114 consumeCpu1(200000);
115 }
116 \&
117 void
118 consumeCpu2(int lim)
119 {
120 for (unsigned int j = 0; j < lim; j++)
121 getppid();
122 }
123 \&
124 void
125 x2(void)
126 {
127 for (unsigned int j = 0; j < 1000; j++)
128 consumeCpu2(10000);
129 }
130 .EE
131 .in
132 .P
133 Now we construct the shared object with the real name
134 .IR libdemo.so.1.0.1 ,
135 and the soname
136 .IR libdemo.so.1 :
137 .P
138 .in +4n
139 .EX
140 $ \fBcc \-g \-fPIC \-shared \-Wl,\-soname,libdemo.so.1 \[rs]\fP
141 \fB\-o libdemo.so.1.0.1 libdemo.c\fP
142 .EE
143 .in
144 .P
145 Then we construct symbolic links for the library soname and
146 the library linker name:
147 .P
148 .in +4n
149 .EX
150 $ \fBln \-sf libdemo.so.1.0.1 libdemo.so.1\fP
151 $ \fBln \-sf libdemo.so.1 libdemo.so\fP
152 .EE
153 .in
154 .P
155 Next, we compile the main program, linking it against the shared object,
156 and then list the dynamic dependencies of the program:
157 .P
158 .in +4n
159 .EX
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)
166 .EE
167 .in
168 .P
169 In order to get profiling information for the shared object,
170 we define the environment variable
171 .B LD_PROFILE
172 with the soname of the library:
173 .P
174 .in +4n
175 .EX
176 $ \fBexport LD_PROFILE=libdemo.so.1\fP
177 .EE
178 .in
179 .P
180 We then define the environment variable
181 .B LD_PROFILE_OUTPUT
182 with the pathname of the directory where profile output should be written,
183 and create that directory if it does not exist already:
184 .P
185 .in +4n
186 .EX
187 $ \fBexport LD_PROFILE_OUTPUT=$(pwd)/prof_data\fP
188 $ \fBmkdir \-p $LD_PROFILE_OUTPUT\fP
189 .EE
190 .in
191 .P
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:
197 .P
198 .in +4n
199 .EX
200 $ \fBrm \-f $LD_PROFILE_OUTPUT/$LD_PROFILE.profile\fP
201 .EE
202 .in
203 .P
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 :
207 .P
208 .in +4n
209 .EX
210 $ \fBLD_LIBRARY_PATH=. ./prog\fP
211 $ \fBls prof_data\fP
212 libdemo.so.1.profile
213 .EE
214 .in
215 .P
216 We then use the
217 .B sprof \-p
218 option to generate a flat profile with counts and ticks:
219 .P
220 .in +4n
221 .EX
222 $ \fBsprof \-p libdemo.so.1 $LD_PROFILE_OUTPUT/libdemo.so.1.profile\fP
223 Flat profile:
224 \&
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
232 .EE
233 .in
234 .P
235 The
236 .B sprof \-q
237 option generates a call graph:
238 .P
239 .in +4n
240 .EX
241 $ \fBsprof \-q libdemo.so.1 $LD_PROFILE_OUTPUT/libdemo.so.1.profile\fP
242 \&
243 index % time self children called name
244 \&
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 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
259 .EE
260 .in
261 .P
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 .P
266 The
267 .B sprof \-c
268 option generates a list of call pairs and the number of their occurrences:
269 .P
270 .in +4n
271 .EX
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
277 .EE
278 .in
279 .SH SEE ALSO
280 .BR gprof (1),
281 .BR ldd (1),
282 .BR ld.so (8)