doc/oprofile.1.in

   1 .TH OPROFILE 1 "@DATE@" "oprofile @VERSION@"
   2 .UC 4
   3 .SH NAME
   4 oprofile \- a system-wide profiler
   5 .SH SYNOPSIS
   6 .br
   7 .B opcontrol
   8 [
   9 .I options
  10 ]
  11 .br
  12 .B opreport
  13 [
  14 .I options
  15 ]
  16 [ profile specification ]
  17 .br
  18 .B opannotate
  19 [
  20 .I options
  21 ]
  22 [ profile specification ]
  23 .br
  24 .B oparchive
  25 [
  26 .I options
  27 ]
  28 [ profile specification ]
  29 .br
  30 .B opgprof
  31 [
  32 .I options
  33 ]
  34 [ profile specification ]
  35 .br
  36 .SH DESCRIPTION
  37 OProfile is a profiling system for systems running Linux
  38 2.6 and greater. Profiling runs transparently in the background and profile
  39 data can be collected at any time. OProfile makes use of the hardware
  40 performance counters provided on Intel, AMD, and other processors,
  41 and uses a timer-interrupt based mechanism on CPUs without counters.
  42 OProfile can profile the whole system in high detail.
  43 .br
  44 For a gentle guide to using OProfile, please read the HTML documentation
  45 listed in SEE ALSO.
  46 .br
  47 .SH OPCONTROL
  48 .B opcontrol
  49 is used for starting and stopping the OProfile daemon, and providing set-up
  50 parameters.
  51 .SH OPREPORT
  52 .B opreport
  53 gives image and symbol-based profile summaries for the whole system or
  54 a subset of binary images.
  55 .SH OPANNOTATE
  56 .B opannotate
  57 can produce annotated source or mixed source and assembly output.
  58 .SH OPARCHIVE
  59 .B oparchive
  60 produces oprofile archive for offline analysis
  61 .SH OPGPROF
  62 .B opgprof
  63 can produce a gprof-format profile for a single binary.
  64
  65 .SH PROFILE SPECIFICATIONS
  66 All of the post-profiling tools can take profile specifications,
  67 which is some combination of the following parameters. Enclosing
  68 part of a profile specification in curly braces { } can be used
  69 for differential profiles with
  70 .B opreport
  71 ; the braces
  72 .B must
  73 be surrounded by whitespace.
  74
  75 .TP
  76 .BI "archive:"archive
  77 Path to the archive to inspect, as generated by
  78 .B oparchive
  79 .br
  80 .TP
  81 .BI "session:"sessionlist
  82 A comma-separated list of session names to resolve in. Absence of this
  83 tag, unlike all others, means "the current session", equivalent to
  84 specifying "session:current".
  85 .br
  86 .TP
  87 .BI "session-exclude:"sessionlist
  88 A comma-separated list of sessions to exclude.
  89 .br
  90 .TP
  91 .BI "image:"imagelist
  92 A comma-separated list of image names to resolve. Each entry may be relative
  93 path, glob-style name, or full path, e.g.
  94 opreport 'image:/usr/bin/oprofiled,*op*,./oprofpp'
  95 .br
  96 .TP
  97 .BI "image-exclude:"imagelist
  98 Same as image:, but the matching images are excluded.
  99 .br
 100 .TP
 101 .BI "lib-image:"imagelist
 102 Same as image:, but only for images that are for
 103 a particular primary binary image (namely, an application). This only
 104 makes sense to use if you're using --separate.
 105 This includes kernel modules and the kernel when using
 106 --separate=kernel.
 107 .br
 108 .TP
 109 .BI "lib-image-exclude:"imagelist
 110 Same as <option>lib-image:</option>, but the matching images
 111 are excluded.
 112 .br
 113 .TP
 114 .BI "event:"eventname
 115 The symbolic event name to match on, e.g. event:DATA_MEM_REFS.
 116 .br
 117 .TP
 118 .BI "count:"eventcount
 119 The event count to match on, e.g. event:DATA_MEM_REFS count:30000.
 120 .br
 121 .TP
 122 .BI "unit-mask:"maskvalue
 123 The unit mask value of the event to match on, e.g. unit-mask:1.
 124 .br
 125 .TP
 126 .BI "cpu:"cpulist
 127 Only consider profiles for the given numbered CPU (starting from zero).
 128 This is only useful when using CPU profile separation.
 129 .br
 130 .TP
 131 .BI "tgid:"pidlist
 132 Only consider profiles for the given task groups. Unless some program is
 133 using threads, the task group ID of a process is the same as its process
 134 ID. This option corresponds to the POSIX notion of a thread group. This
 135 is only useful when using per-process profile separation.
 136 .br
 137 .TP
 138 .BI "tid:"tidlist
 139 Only consider profiles for the given threads. When using recent thread
 140 libraries, all threads in a process share the same task group ID, but
 141 have different thread IDs. You can use this option in combination with
 142 tgid: to restrict the results to particular threads within a process.
 143 This is only useful when using per-process profile separation.
 144
 145 .SH ENVIRONMENT
 146 No special environment variables are recognised by oprofile.
 147
 148 .SH FILES
 149 .TP
 150 .I $HOME/.oprofile/
 151 Configuration files
 152 .TP
 153 .I /root/.oprofile/daemonrc
 154 Configuration file for opcontrol
 155 .TP
 156 .I @prefix@/share/oprofile/
 157 Event description files used by OProfile.
 158 .TP
 159 .I /var/lib/oprofile/samples/oprofiled.log
 160 The user-space daemon logfile.
 161 .TP
 162 .I /dev/oprofile
 163 The device filesystem for communication with the Linux kernel module.
 164 .TP
 165 .I /var/lib/oprofile/samples/
 166 The location of the generated sample files.
 167
 168 .SH VERSION
 169 .TP
 170 This man page is current for @PACKAGE@-@VERSION@.
 171
 172 .SH SEE ALSO
 173 .BR @OP_DOCDIR@,
 174 .BR opcontrol(1),
 175 .BR opreport(1),
 176 .BR opannotate(1),
 177 .BR oparchive(1),
 178 .BR opgprof(1),
 179 .BR gprof(1),
 180 .BR readprofile(1),
 181 .BR "CPU vendor architecture manuals"
 182
 183 .SH COPYRIGHT
 184 oprofile is Copyright (C) 1998-2004 University of Manchester, UK, John Levon,
 185 and others.
 186 OProfile is released under the GNU General Public License, Version 2,
 187 or (at your option) any later version.
 188 .SH AUTHORS
 189 John Levon <levon@movementarian.org> is the primary author. See the documentation
 190 for other contributors.