Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
PMCSTAT(8)              FreeBSD System Manager's Manual             PMCSTAT(8)

     pmcstat - performance measurement with performance monitoring hardware

     pmcstat [-C] [-D pathname] [-E] [-O logfilename] [-P event-spec]
             [-R logfilename] [-S event-spec] [-W] [-c cpu] [-d] [-g]
             [-k kernelfile] [-n rate] [-o outputfile] [-p event-spec]
             [-s event-spec] [-t pid] [-w secs] [command [args]]

     The pmcstat utility measures system performance using the facilities
     provided by hwpmc(4).

     The pmcstat utility can measure both hardware events seen by the system
     as a whole, and those seen when a specified process is executing on the
     system's CPUs.  If a specific process is being targeted (for example, if
     the -t pid option is specified, or if a command line is specified using
     command), then measurement occurs till the target process exits or the
     pmcstat utility is interrupted by the user.  If a specific process is not
     targeted for measurement, then pmcstat will perform system-wide
     measurements till interrupted by the user.

     A given invocation of pmcstat can mix allocations of system-mode and
     process-mode PMCs, of both counting and sampling flavors.  The values of
     all counting PMCs are printed in human readable form at regular intervals
     by pmcstat.  The output of sampling PMCs may be configured to go to a log
     file for subsequent offline analysis, or, at the expense of greater
     overhead, may be configured to be printed in text form on the fly.

     Hardware events to measure are specified to pmcstat using event specifier
     strings event-spec.  The syntax of these event specifiers is machine
     dependent and is documented in pmc(3).

     A process-mode PMC may be configured to be inheritable by the target
     process' current and future children.

     The following options are available:

     -C      Toggle between showing cumulative or incremental counts for
             subsequent counting mode PMCs specified on the command line.  The
             default is to show incremental counts.

     -D pathname
             Create files with per-program samples in the directory named by
             pathname.  The default is to create these files in the current

     -E      Toggle showing per-process counts at the time a tracked process
             exits for subsequent process-mode PMCs specified on the command
             line.  This option is useful for mapping the performance
             characteristics of a complex pipeline of processes when used in
             conjunction with the -d option.  The default is to not to enable
             per-process tracking.

     -O logfilename
             Send logging output to file logfilename.  If this option is not
             specified and one of the logging options is requested, then
             pmcstat will print a textual form of the logged events to the
             configured output file.

     -P event-spec
             Allocate a process mode sampling PMC measuring hardware events
             specified in event-spec.

     -R logfilename
             Perform offline analysis using sampling data in file logfilename.

     -S event-spec
             Allocate a system mode sampling PMC measuring hardware events
             specified in event-spec.

     -W      Toggle logging the incremental counts seen by the threads of a
             tracked process each time they are scheduled on a CPU.  This is
             an experimental feature intended to help analyse the dynamic
             behaviour of processes in the system.  It may incur substantial
             overhead if enabled.  The default is for this feature to be

     -c cpu  Set the cpu for subsequent system mode PMCs specified on the
             command line to cpu.  The default is to allocate system mode PMCs
             on CPU zero.

     -d      Toggle between process mode PMCs measuring events for the target
             process' current and future children or only measuring events for
             the target process.  The default is to measure events for the
             target process alone.

     -g      Produce flat execution profiles in a format compatible with
             gprof(1).  A separate profile file is generated for each
             executable object encountered.  Profile files are placed in sub-
             directories named by their PMC event name.

     -k kernelfile
             Set the pathname of the kernel to argument kernelfile.  The
             default is /boot/kernel/kernel.

     -n rate
             Set the default sampling rate for subsequent sampling mode PMCs
             specified on the command line.  The default is to configure PMCs
             to sample the CPU's instruction pointer every 65536 events.

     -o outputfile
             Send counter readings and textual representations of logged data
             to file outputfile.  The default is to send output to stderr.

     -p event-spec
             Allocate a process mode counting PMC measuring hardware events
             specified in event-spec.

     -s event-spec
             Allocate a system mode counting PMC measuring hardware events
             specified in event-spec.

     -t pid  Attach all process mode PMCs allocated to the process with PID
             pid.  The option is not allowed in conjunction with specifying a
             command using command.

     -w secs
             Print the values of all counting mode PMCs every secs seconds.
             The argument secs may be a fractional value.  The default
             interval is 5 seconds.

     If command is specified, it is executed using execvp(3).

     To perform system-wide statistical sampling on an AMD Athlon CPU with
     samples taken every 32768 instruction retirals and data being sampled to
     file sample.stat, use:
           pmcstat -O sample.stat -n 32768 -S k7-retired-instructions

     To execute mozilla and measure the number of data cache misses suffered
     by it and its children every 12 seconds on an AMD Athlon, use:
           pmcstat -d -w 12 -p k7-dc-misses mozilla

     To collect a system-wide samples driven by processor instructions
     executed use:
           pmcstat -S instructions -O /tmp/sample.out

     To generate gprof(1) compatible flat profiles from a sample file use:
           pmcstat -R /tmp/sample.out -g

     The pmcstat utility exits 0 on success, and >0 if an error occurs.

     gprof(1), execvp(3), pmc(3), pmclog(3), hwpmc(4), pmccontrol(8),

     The pmcstat utility first appeared in FreeBSD 6.0.  It is currently under

     Joseph Koshy <>

FreeBSD 11.0-PRERELEASE          July 1, 2005          FreeBSD 11.0-PRERELEASE


Want to link to this manual page? Use this URL:

home | help