Maintenance Commands                                  cpustat(1M)

NAME
     cpustat - monitor  system  behavior  using  CPU  performance
     counters

SYNOPSIS
     cpustat -c eventspec   [ -c eventspec ]  ...  [  -ntD  ]   [
     interval  [ count ]  ]

     cpustat -h

DESCRIPTION
     The cpustat utility allows CPU performance  counters  to  be
     used to monitor the overall behavior of the CPUs in the sys-
     tem.

     If interval is specified,  cpustat  samples  activity  every
     interval  seconds,  repeating forever.  If a count is speci-
     fied, the statistics are repeated count  times.  If  neither
     are  specified,  an  interval  of  five seconds is used, and
     there is no limit to the number  of  samples  that  will  be
     taken.

OPTIONS
     The following options are supported:

     -c eventspec
           Specify a  set  of  events  for  the  CPU  performance
           counters to monitor. The syntax of these event specif-
           ication can be determined using the -h option to cause
           the  usage  message  to be generated. The semantics of
           these event specifications can be determined by  read-
           ing   the  CPU  manufacturers  documentation  for  the
           events. See cpc_strtoevent(3CPC) for a description  of
           the syntax.

           Multiple -c options may be specified,  in  which  case
           the  command  cycles  between the different event set-
           tings on each sample.

     -D    Enable debug mode.

     -h    Print an extensive help message  on  how  to  use  the
           utility  and  how  to  program the processor-dependent
           counters.

     -n    Omit all header  output  (useful  if  cpustat  is  the
           beginning of a pipeline).

     -t    Print an additional column of processor cycle  counts,
           if available on the current architecture.

SunOS 5.8           Last change: 14 Sep 1999                    1

Maintenance Commands                                  cpustat(1M)

USAGE
     A closely related utility, cputrack(1), can be used to moni-
     tor  the  behavior of individual applications with little or
     no interference from other activities on the system.

     The cpustat utility must be run by the super-user, as  there
     is  an intrinsic conflict between the use of the CPU perfor-
     mance counters system-wide by cpustat and the use of the CPU
     performance  counters  to monitor an individual process (for
     example, by cputrack.)

     Once any instance of this utility has  started,  no  further
     per-process  or per-LWP use of the counters is allowed until
     the last instance of the utility terminates.

     The times printed by the command correspond to the wallclock
     time  when  the  hardware  counters  were  actually sampled,
     instead of when the program told the kernel to sample  them.
     The time is derived from the same timebase as gethrtime(3C).

     The processor cycle counts enabled by the -t  option  always
     apply  to both user and system modes, regardless of the set-
     tings applied to the performance counter registers.

     The output of cpustat is designed to be readily parseable by
     nawk(1)  and  perl(1), thereby allowing performance tools to
     be composed by embedding cpustat in scripts.  Alternatively,
     tools  may  be constructed directly using the same APIs that
     cpustat is built upon using the facilities of  libcpc(3LIB).
     See cpc(3CPC).

     The cpustat utility only monitors the CPUs that are accessi-
     ble  to  it  in  the  current  processor  set.  Thus several
     instances of the  utility can be running on the CPUs in dif-
     ferent  processor  sets. See psrset(1M) for more information
     about processor sets.

     Because cpustat uses LWPs bound to  CPUs,  the  utility  may
     have  to terminated before the configuration of the relevant
     processor can be changed.

WARNING
     By running the cpustat command, the superuser will  forcibly
     invalidate  all existing performance counter context.   This
     may in turn cause all invocations of the  cputrack  command,
     and  other  users  of  performance  counter context, to exit
     prematurely with unspecified errors.

ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:

SunOS 5.8           Last change: 14 Sep 1999                    2

Maintenance Commands                                  cpustat(1M)

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    | Availability                | SUNWcpcu                    |
    | Interface Stability         | Evolving                    |
    |_____________________________|_____________________________|

SEE ALSO
     cputrack(1),  nawk(1),  perl(1),   iostat(1M),   prstat(1M),
     psrset(1M),   vmstat(1M),  cpc(3CPC),  cpc_strtoevent(3CPC),
     gethrtime(3C), libcpc(3LIB), attributes(5)

     Sun Microelectronics UltraSPARC I&II User's Manual,  January
     1997, STP1031, http://www.sun.com/sparc

     Intel Architecture Software Developer's  Manual,  Volume  3:
     System Programmers Guide, 243192, http://developer.intel.com

SunOS 5.8           Last change: 14 Sep 1999                    3