Debian Codegraph @

upstream/debian-unstable/man1/sprof.1

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