man1/sprof.1

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