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
           Specifies 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 can be specified,  in  which  case
           the  command  cycles  between the different event set-
           tings on each sample.

     -D    Enables debug mode.

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

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

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

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.

     On some hardware platforms,  the  counters  are  implemented
     using  32-bit  registers. While the kernel attempts to catch
     all overflows to  synthesize  64-bit  counters,  because  of
     hardware  implementation restrictions, overflows can be lost
     unless the sampling  interval  is  kept  short  enough.  The
     events  most  prone  to  wrap are those that count processor
     clock cycles. If such an  event  is  of  interest,  sampling
     should  occur  frequently  so that less than 4 billion clock
     cycles can occur between samples.

     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  can  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  might
     have  to  be  terminated  before  the  configuration  of the
     relevant processor can be changed.

WARNINGS

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

     If cpustat is invoked on a system that has  CPU  performance
     counters,  but  on  which the packages containing the kernel
     support for those counters is not installed,  the  following
     message appears:

     cpustat: CPU performance counters are inaccessible on this machine

     This error message implies that cpc_access() has failed  and
     is documented in cpc_access(3CPC). Review this documentation
     for more information about the problem  and  possible  solu-
     tions.

     If a short interval is requested, cpustat might not be  able
     to  keep up with the desired sample rate. In this case, some
     samples might be dropped.

ATTRIBUTES

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

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

cpustat(1M)

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

USAGE

WARNINGS

ATTRIBUTES

SEE ALSO