1 .TH XCPUSTATE 1 "Mar 29, 1996" 
  2 .SH NAME
  3 xcpustate - display CPU states (idle, nice, system, kernel) statistics
  4 .SH SYNTAX
  5 \fBxcpustate\fP [\fI -toolkitoption\fP ...] [\fI -count\fP iterations] 
  6 [\fI -interval\fP seconds] [\fI -shorten\fP components]
  7 [\fI -cpu\fP] [\fI -nocpu\fP] [\fI -disk\fP] [\fI -nodisk\fP] [\fI -omni\fP] 
  8 [\fI -noomni\fP] [\fI -wait\fP] [\fI -nowait\fP] 
  9 [\fI -filltype\fP auto|grayscale|color|tile|stipple] 
 10 [\fI -host\fP hostname] [\fI -version\fP]
 11 [\fI -colors\fP colorname[,colorname[,...]]] 
 12 [\fI -avg\fP iterations][\fI -kernel pathname] [\fI -mmap] [\fI -nommap]
 13 .SH DESCRIPTION
 14 .I Xcpustate
 15 displays bars showing the percentage of time the CPU spends in
 16 different states. On some systems, it optionally indicates disk states in
 17 the same manner. It can also query remote systems that offer RSTAT RPC services.
 18 .PP
 19 When using the RSTAT protocol, or when running locally on machines running 
 20 Linux, or Berkeley Unix or a derivative (eg. suns with SunOS<=4.1.1, 
 21 microVaxen with Ultrix), the bar indicates the proportions of idle, user, 
 22 nice, and system time with increasing levels of grayscale or color (from 
 23 left to right).  When running locally on supported multiprocessors 
 24 (Solbourne OS/MP systems, Ultrix multiprocessors, Linux/SMP, and the 
 25 Gould NP1), there will be one bar for each CPU. 
 26 .PP
 27 On an SGI system running IRIX, there will be one bar for each CPU, indicating 
 28 the proportions of idle + wait, user, kernel, sxbrk and interrupt time for 
 29 that CPU. If  the ``wait'' option is set, the bars indicate idle, wait, user, 
 30 kernel, sxbrk, and interrupt time, from left to right.
 31 .PP
 32 On a Sun multiprocessor under SunOS 4.1.2 or 4.1.3, bars indicate the
 33 proportions of idle + diskwait, user, nice, system, spinlock, and crosscall
 34 service time for each CPU.
 35 .PP
 36 On a Sun or other system (eg. Solbourne, Cray Superserver-6400) running 
 37 Solaris 2.x, and on an IBM system running AIX, bars indicate the proportions 
 38 of idle + wait, user, and kernel time for each CPU.  If the ``wait'' option 
 39 is set, the bars indicate idle, wait, user, and system/kernel time, 
 40 from left to right.
 41 .PP
 42 On a Cray X/MP or Y/MP running Unicos 5.1 or greater, bars indicate
 43 the proportions of idle + wait, user and system/kernel time for each CPU. 
 44 .PP
 45 On systems running the Mach operating system, bars indicates the
 46 proportions of user, system, and idle time for each CPU.
 47 .PP
 48 On supported SVR4 systems (at least DELL Unix 2.2), a single bar is 
 49 displayed showing idle, user, system and wait times.
 50 .PP
 51 On NCR SVR4 MP/RAS systems,
 52 one bar for each CPU (or disk drive) is displayed.
 53 Each bar indicates the relative proportions of idle, user, system and
 54 wait times for that CPU.  Disk drive times show device idle and busy.
 55 .SH OPTIONS
 56 .I Xcpustate
 57 accepts all of the standard X Toolkit command line options, plus:
 58 .TP 8
 59 .IR -count " iterations"
 60 The number of times it should update the display. Default is forever.
 61 .TP 8
 62 .IR -avg " iterations"
 63 The number of iterations the bar values should be averaged over. Default is one.
 64 .TP 8
 65 .IR -interval " seconds"
 66 the interval in seconds (fractions permitted) between updates.  Default is 
 67 1 second.
 68 .TP 8
 69 .IR -shorten " components"
 70 On some systems, 
 71 .I xcpustate 
 72 will display the hostname in the bar labels.  Since some fully
 73 qualified domain names can be very long, this option allows them
 74 to be shortened to a specific number of components.  eg.
 75 if your hostname is 
 76 .I foo.wherever.edu,
 77 you can shorten it to
 78 .I foo
 79 by specifying
 80 .I "-shorten 1"
 81 or to
 82 .I foo.wherever
 83 by specifying
 84 .I "-shorten 2".
 85 Specifying
 86 .I "-shorten 0"
 87 will omit the hostname completely; a negative number will cause
 88 .I xcpustate
 89 to draw unlabeled bars.
 90 Some systems may not support this option.
 91 .TP 8
 92 .I -cpu
 93 Display CPU statistics (default).
 94 .TP 8
 95 .I -nocpu
 96 Do not display CPU statistics. 
 97 .TP 8
 98 .I -disk
 99 Display Disk statistics. This is supported only on Suns running SunOS 4.x or
100 5.x, or when using RSTAT. One bar is displayed for each disk. Disk bars appear
101 below the CPU bars, if any. When using RSTAT, exactly four bars appear 
102 regardless of the number of disks on the remote host (this is a limitation
103 of the current version of the RSTAT protocol). For Suns running SunOS 4.x,
104 the bars report idle, seek, and transfer time. For Suns running SunOS 5.x, 
105 the bars report idle, wait, and run time. When RSTAT is being used, the 
106 bars report idle and transfer time.
107 .TP 8
108 .I -nodisk
109 Do not display disk statistics (default).
110 .TP 8
111 .I -omni
112 Display Omni Network Coprocessor Statistics. This is supported only on
113 Suns running SunOS 4.x. One bar is displayed for each Network Coprocessor,
114 and placed immediately below the bars for the regular CPU(s). Each bar
115 indicates idle and system time.
116 .TP 8
117 .I -noomni
118 Do not display omni statistics (default).
119 .TP 8
120 .I -wait
121 Display CPU disk/system wait time as a separate statistic on applicable 
122 systems (Eg. SunOS 5.x, SGI IRIX, IBM AIX). 
123 .TP 8
124 .I -nowait
125 Include CPU disk/system wait time as part of idle (default).
126 .TP 8
127 .I -version
128 Print out version information and exit.
129 .TP 8
130 .I -filltype
131 Specify the method 
132 .B xcpustate 
133 should use to fill the bars. Available options include grayscale,
134 color, tile, stipple, or auto. Auto automatically chooses between tiling,
135 grayscale, and colour, depending on your display type. Auto is the default.
136 .TP 8
137 .I -colors
138 Specify the colors used to draw the bars. Colors are specified in 
139 left-to-right order, separated by commas. A single dot can be used to
140 specify the default color at that position. Up to ten colors may be specified.
141 Defaults are used for the leftmost colors if less than ten are specified. 
142 .TP 8
143 .IR -kernel " pathname"
144 Specify the path that
145 .B xcpustate
146 will use to find kernel symbol file information on some systems. This option
147 is ignored on IRIX, Mach, and SunOS 5.x.
148 .TP 8
149 .I -mmap
150 Request that
151 .B xcpustate
152 use mmap to directly map kernel memory into the current process address
153 space on some systems (SVR4 and NCR). This is the default.
154 .TP 8
155 .I -nommap
156 Inverse of mmap option. 
157 .SH X DEFAULTS
158 For
159 .I xcpustate
160 the available class identifiers are:
161 .sp
162 .nf
163 CPUStateMonitor - the application
164 Form - enclosing the entire application, and sub-Forms enclosing 
165 Label/Bar pairs.
166 .fi
167 .PP
168 For
169 .I xcpustate,
170 the available name identifiers are:
171 .sp
172 .nf
173 xcpustate - application name
174 The outer Form is "form".
175 The Forms enclosing the Label/Bar pairs are "formN", where N is the
176 index number, starting with the top pair as zero.
177 Each Label name is the same as the label string.
178 Each Bar name is "barN".
179 .fi
180 .sp
181 .LP
182 For
183 .I xcpustate,
184 the available resources are:
185 .IP "name interval, class Interval"
186 corresponds to the -interval option. Takes a float value.
187 .IP "name count, class Count"
188 corresponds to the -count argument. Takes an integer value.
189 .IP "name avg, class Avg"
190 corresponds to the -avg argument. Takes an integer value.
191 .IP "name shorten, class Shorten"
192 corresponds to the -shorten argument. Takes an integer value.
193 .IP "name cpu, class Cpu"
194 corresponds to the -cpu and -nocpu arguments. Takes a boolean value.
195 .IP "name disk, class Disk"
196 corresponds to the -disk and -nodisk arguments. Takes a boolean value.
197 .IP "name omni, class Omni"
198 corresponds to the -omni and -noomni arguments. Takes a boolean value.
199 Not available on systems other than Suns running SunOS 4.x.
200 .IP "name wait, class Wait"
201 corresponds to the -wait and -nowait arguments. Takes a boolean value.
202 .IP "name filltype, class Filltype"
203 corresponds to the -filltype argument. Takes a string.
204 .IP "name host, class Host"
205 corresponds to the -host argument. Takes a hostname.
206 .IP "name colors, class Colors"
207 corresponds to the -colors argument. Takes a comma-separated list of color
208 names. 
209 .IP "name mmap, class Mmap"
210 corresponds to the -mmap and -nommap argument. Takes a boolean value.
211 .IP "name kernel, class Kernel"
212 corresponds to the -kernel argument. Takes a pathname.
213 .SH NOTES
214 .I Xcpustate 
215 is meant to be easy to port, and extend to monitor a wide variety of statistics.
216 .SH SEE ALSO
217 xperfmon, xload, xmeter
218 .SH AUTHORS
219 Mark Moraes at D. E. Shaw wrote the original X code and the SGI IRIX
220 code. He also enhanced the code for the Bar widget to support color. 
221 John DiMarco at the University of Toronto is the current maintainer. He 
222 contributed to the color support, fixed some minor problems, added support for
223 SunOS 4.x multiprocessors, SunOS 5.x, disks, Omni network coprocessors, AIX
224 (SMP on AIX 4.x) and RSTAT. Thanks to David O'Brien of the University of
225 California, Davis for the Free/Net/OpenBSD code, Chris Siebenmann of the
226 University of Toronto for the code for 4.3BSD systems; Walter D. Poxon from
227 Cray Research for the code for Cray machines running Unicos; Melinda Shore at
228 mt Xinu for the code for Mach systems; Bill Kucharski at Solbourne for the
229 code for Solbourne systems; Salvador Pinto Abreu at Universidade Nova de
230 Lisboa, Portugal, for the code for Ultrix multiprocessors; Hugues Leroy at
231 Irisa, Rennes, France for the code for Gould NP1 bi-processors, Bruce
232 Frost at NCR for the code for (Dell) SVR4 and NCR systems, and Kumsup Lee
233 at the University of Minnesota for the Linux code. Thanks also to
234 Robert Montjoy from the University of Cincinatti for contributing and testing
235 some of the SunOS 5.x code, to Dave Cahlander from Cray for cleaning up the X
236 resource code, and to Ron Wigmore from Ryerson Polytechnic University for his
237 assistance with the AIX port.
238 .SH BUGS
239 The RSTAT RPC protocol supports only one processor and four disks on the 
240 remote system. On a multiprocessor, the CPU data reported by RSTAT will
241 be an average of all the active CPUs on the machine.
242 .PP
243 .I Xcpustate
244 may initially display nonsensical data, before being updated the first time.
245 .PP
246 The use of very small (significantly less than one second) intervals may
247 result in xcpustate using significant resources, particularly when running
248 over the network.  A minimum interval may be specified as a compile-time
249 option, and intervals less than this will not be permitted.