Debian Codegraph @

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