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

FreeBSD Manual Pages


home | help
PMCSTAT(8)		  BSD 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 pro-
     vided 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 measure-
     ments 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 over-
     head, 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 de-
     pendent 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 sub-
	     sequent 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 charac-
	     teristics of a complex pipeline of	processes when used in con-
	     junction 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 be-
	     haviour of	processes in the system.  It may incur substantial
	     overhead if enabled.  The default is for this feature to be dis-

     -c	cpu  Set the cpu for subsequent	system mode PMCs specified on the com-
	     mand 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 exe-
	     cutable object encountered.  Profile files	are placed in sub-di-
	     rectories named by	their PMC event	name.

     -k	kernelfile
	     Set the pathname of the kernel to argument	kernelfile.  The de-
	     fault 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 inter-
	     val 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 exe-
     cuted 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 <>

BSD				 July 1, 2005				   BSD


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

home | help