.TH SARPLOT 1 "30 June 1995"
.SH NAME
sarplot \- plot statistics gathered by sar
.br
.\"
.\" we don't need a .br/.ne 5 here since there
.\" isn't any chance really, that we're already
.\" anywhere near the end of the first page.
.\"
.SH SYNOPSIS
.B "sarplot \-V"
.br
.B "sarplot"
[ 
.B \-verb
.I level
] [
.B \-show
] [ 
.B \-x11
|
.B \-ps
] [ { 
.B \-hr
|
.B \-hrs
} [
.I count
] ] [ {
.B \-day
|
.B \-days
} [
.I count
] ] [ {
.B \-week
|
.B \-weeks
} [
.I count
] ] [
.B \-from
.I timestamp
] [
.B \-to
.I timestamp
] [ 
.B \-u
[
.I factor 
]
] [
.B \-upu 
[
.I factor 
]
] [
.B \-ups
[
.I factor 
]
] [
.B \-upw
[
.I factor 
]
] [ 
.B \-upi
[
.I factor 
]
] [
.B \-b
[
.I factor 
]
] [
.B \-brd
[
.I factor 
]
] [
.B \-brc
[
.I factor 
]
] [ 
.B \-brh
[
.I factor 
]
] [ 
.B \-brp
[
.I factor 
]
] [
.B \-bwd
[
.I factor 
]
] [
.B \-bwc
[
.I factor 
]
] [
.B \-bwh
[
.I factor 
]
] [ 
.B \-bwp
[
.I factor 
]
] [
.B \-d
[
.I factor 
]
] [
.B \-dpb
[
.I factor 
]
] [ 
.B \-dlq
[
.I factor 
]
] [
.B \-dxc
[
.I factor 
]
] [
.B \-dxb
[
.I factor 
]
] [
.B \-dtw
[
.I factor 
]
] [
.B \-dts
[
.I factor 
]
] [
.B \-y
[
.I factor 
]
] [
.B \-yrc
[
.I factor 
]
] [
.B \-ycc
[
.I factor 
]
] [
.B \-ywc
[
.I factor 
]
] [
.B \-yri
[
.I factor 
]
] [
.B \-ywi
[
.I factor 
]
] [
.B \-ymi
[
.I factor 
]
] [
.B \-c
[
.I factor 
]
] [
.B \-cca
[
.I factor 
]
] [
.B \-ccr
[
.I factor 
]
] [
.B \-ccw
[
.I factor 
]
] [
.B \-ccf
[
.I factor 
]
] [
.B \-cce
[
.I factor 
]
] [
.B \-crc
[
.I factor 
]
] [
.B \-cwc
[
.I factor 
]
] [
.B \-w
[
.I factor 
]
] [
.B \-wrs
[
.I factor 
]
] [
.B \-wrb
[
.I factor 
]
] [
.B \-wws
[
.I factor 
]
] [
.B \-wwb
[
.I factor 
]
] [
.B \-wxc
[
.I factor 
]
] [
.B \-a
[
.I factor 
]
] [
.B \-aci
[
.I factor 
]
] [
.B \-acl
[
.I factor 
]
] [
.B \-arb
[
.I factor 
]
] [
.B \-q
[
.I factor 
]
] [ 
.B \-qlr
[
.I factor 
]
] [
.B \-qpr
[
.I factor 
]
] [
.B \-qls
[
.I factor 
]
] [
.B \-qps
[
.I factor 
]
] [
.B \-v
[
.I factor 
]
] [
.B \-vpt
[
.I factor 
]
] [
.B \-vot
[
.I factor 
]
] [
.B \-vpp
[
.I factor 
]
] [
.B \-vop
[
.I factor 
]
] [
.B \-vpi
[
.I factor 
]
] [
.B \-voi
[
.I factor 
]
] [
.B \-vpf
[
.I factor 
]
] [
.B \-vof
[
.I factor 
]
] [
.B \-m
[
.I factor 
]
] [
.B \-mcm
[
.I factor 
]
] [
.B \-mcs
[
.I factor 
]
] {
.I sarfile
|
.I compressed_sarfile
|
.I gnuzipped_sarfile
} ...
.br
.\"
.\" we don't need a .br/.ne 5 here since there
.\" isn't any chance really, that we're already
.\" anywhere near the end of the first page.
.\"
.SH DESCRIPTION
This man page documents 
.I sarplot 
version "Fri Jun 30 11:38:42 BST 1995".
.PP
.I Sarplot
is a Perl (see 
.I perl\fR(1))
script which invokes 
.I sar\fR(1),
tidies the resulting stream of data and feeds it, 
together with several formatting instructions, to
.I gnuplot\fR(1). 
.PP
Graphs can be plotted directly into an X window or
outputted in postscript format suitable for piping to
.I lp\fR(1).
.PP 
Data selection options are compatible with
.I sar\fR(1),
with the exception of 
.I sar\fR(1)'s
.B \-A
option which is not supported. See WARNINGS for an 
explanation of this. 
In addition there are options for plotting individual
columns of 
.I sar\fR(1)
data.
.PP
.I Sarplot
will process raw sarfiles, or sarfiles compressed with
.I compress\fR(1) 
or 
.I gzip\fR(1). Temporary raw sarfiles are created in
these latter cases, without actually uncompressing the
original files; which means that the sarfiles and the
directories they are stored in do not have to be writable
by the user invoking
.I sarplot\fR.
.PP 
In addtion to the options specifying which graphs are
to be plotted, a scaling factor may also be supplied. This
is primarily intended to help locate a new maximum 
value for a particular 
.I sar\fR(1)
column. See WARNINGS for more information.
.br
.ne 5
.SH OPTIONS
.\"  This indents everything after the next line by 25 somethings.
.TP 25
.B \-V
Print the version number and exit.
.TP
.B \-verb \fIlevel
Sets the verbosity level. If 
.I level
is set to 0, then not even 
error messages will be reported.
If 
.I level 
is set to 1, then only error messages will be reported.
If 
.I level
is set to 2, which is the default, then
error and warning messages will be reported. If
.I level
is set to 3, then additional informational messages 
will also be reported. If 
.I level
is set to 4 or greater then additional debugging 
messages are reported.
.TP
.B \-show
Commands will not be fed to
.I gnuplot\fR(1),
but will be sent to standard output. This is really only 
useful for debugging.
.TP
.B \-x11
Specifies that graphs should be displayed in an
X window (see 
.I X\fR(1)). This is the default. As with and
.I X Windows application access to the destination display
must be authorised (see
.I xhost\fR(1)).
.I sa
.TP
.B \-ps
Specifies that Postscript output, suitable for piping to 
.I lp\fR(1),
should be sent to the standard output. 
.I Sarplot
will not pause between pages if this option is used.
.TP
.B \-hr\fR, \fB\-hrs\fR [ \fIcount\fR ]
Specifies that each page of the graph should cover
a period of 
.I count
hours. If 
.I count
is missing, then a value of 1 is assumed.
.TP
.B \-day\fR, \fB\-days\fR [ \fIcount\fR ]
Specifies that each page of the graph should cover
a period of
.I count
days. If
.I count
is missing, then a value of 1 is assumed. 1 day
per page is the default.
.TP
.B \-week\fR, \fB\-weeks\fR [ \fIcount\fR ]
Specifies that each page of the graph should cover
a period of
.I count
weeks. If
.I count
is missing, then a value of 1 is assumed. Pages
of this type show Monday as the first day of the
week.
.TP
.B \-from \fItimestamp
Specifies that the graph should begin at the date
and time specified by
.I timestamp\fR,
which should be in the format 
.B YYMMDDhhmm\fR.
This will result in the graph being either shortened
or lengthened according to the relationship between
.I timestamp
and the actual earliest timestamp in the 
.I sar\fR(1)
data.
.TP
.B \-to \fItimestamp
Specifies that the graph should end at the date
and time specified by
.I timestamp\fR,
which should be in the format
.B YYMMDDhhmm\fR.
This will result in the graph being either shortened
or lengthened according to the relationship between
.I timestamp
and the actual latest timestamp in the 
.I sar\fR(1)
data.
.TP
.B \-u
This option shows the graphs associated with
the 
.I sar\fR(1)
option 
.B \-u\fR.
.TP
.B \-upu\fR, \fB\-ups\fR, \fB\-upw\fR, \fB\-upi
These options show individual graphs associated
with the
.I sar\fR(1)
option
.B \-u\fR.
The first letter is derived from the equivalent
option in 
.I sar\fR(1),
the second letter stands for 
.I processor\fR,
and the third letters stand for 
.I user\fR,
.I system\fR,
.I waiting\fR
and 
.I idle\fR.
.TP
.B \-b
This option shows the graphs associated with
the
.I sar\fR(1)
option
.B \-b\fR.
.TP
.B \-brd\fR, \fB\-brc\fR, \fB\-brh\fR, \fB\-brp\fR, \fB\-bwd\fR, \fB\-bwc\fR, \fB\-bwh\fR, \fB\-bwp\fR
These options show individual graphs associated
with the
.I sar\fR(1)
option
.B \-b\fR.
The first letter is derived from the equivalent
option in
.I sar\fR(1),
the second letters stand for
.I read\fR
and 
.I write
and the third letters stand for
.I device\fR,
.I cache\fR,
.I hits\fR
and
.I physical\fR.
.TP
.B \-d
This option shows the graphs associated with
the
.I sar\fR(1)
option
.B \-d\fR.
.TP
.B \-dpb\fR, \fB\-dlq\fR, \fB\-dxc\fR, \fB\-dxb\fR, \fB\-dtw\fR, \fB\-dts\fR
These options show individual graphs associated
with the
.I sar\fR(1)
option
.B \-d\fR.
The first letter is derived from the equivalent
option in
.I sar\fR(1),
the second letters stand for
.I percentage,\fR
.I length,\fR
.I transfer
and
.I time
and the third letters stand for
.I busy\fR,
.I queue\fR,
.I count\fR,
.I blocks\fR,
.I wait
and
.I serve\fR.
.TP
.B \-y
This option shows the graphs associated with
the
.I sar\fR(1)
option
.B \-y\fR.
.TP
.B \-yrc\fR, \fB\-ycc\fR, \fB\-ywc\fR, \fB\-yri\fR, \fB\-ywi\fR, \fB\-ymi\fR
These options show individual graphs associated
with the
.I sar\fR(1)
option
.B \-y\fR.
The first letter is derived from the equivalent
option in
.I sar\fR(1),
the second letters stand for
.I read,\fR
.I call,\fR
.I write
and
.I modem
and the third letters stand for
.I characters\fR,
.I canon()
and
.I interrupts\fR.
.TP
.B \-c
This option shows the graphs associated with
the
.I sar\fR(1)
option
.B \-c\fR.
.TP
.B \-cca\fR, \fB\-ccr\fR, \fB\-ccw\fR, \fB\-ccf\fR, \fB\-cce\fR, \fB\-crc\fR, \fB\-cwc\fR
These options show individual graphs associated
with the
.I sar\fR(1)
option
.B \-c\fR.
The first letter is derived from the equivalent
option in
.I sar\fR(1),
the second letters stand for
.I call,\fR
.I read
and
.I write
and the third letters stand for
.I all\fR,
.I read()\fR,
.I write()\fR,
.I fork()\fR,
.I exec()
and
.I count\fR.
.TP
.B \-w
This option shows the graphs associated with
the
.I sar\fR(1)
option
.B \-w\fR.
.TP
.B \-wrp\fR, \fB\-wrb\fR, \fB\-wwp\fR, \fB\-wwb\fR, \fB\-wxc\fR
These options show individual graphs associated
with the
.I sar\fR(1)
option
.B \-w\fR.
The first letter is derived from the equivalent
option in
.I sar\fR(1),
the second letters stand for
.I read,\fR
.I write
and
.I switch
and the third letters stand for
.I processes\fR,
.I blocks
and
.I context\fR.
.TP
.B \-a
This option shows the graphs associated with
the
.I sar\fR(1)
option
.B \-a\fR.
.TP
.B \-aci\fR, \fB\-acl\fR, \fB\-arb\fR
These options show individual graphs associated
with the
.I sar\fR(1)
option
.B \-a\fR.
The first letter is derived from the equivalent
option in
.I sar\fR(1),
the second letters stand for
.I call
and
.I read
and the third letters stand for
.I iget()\fR,
.I lookuppn()
and
.I blocks\fR.
.TP
.B \-q
This option shows the graphs associated with
the
.I sar\fR(1)
option
.B \-q\fR.
.TP
.B \-qlr\fR, \fB\-qpr\fR, \fB\-qls\fR, \fB\-qps\fR
These options show individual graphs associated
with the
.I sar\fR(1)
option
.B \-q\fR.
The first letter is derived from the equivalent
option in
.I sar\fR(1),
the second letters stand for
.I length\fR,
and
.I percentage
and the third letters stand for
.I run\fR
and
.I swap\fR.
.TP
.B \-v
This option shows the graphs associated with
the
.I sar\fR(1)
option
.B \-v\fR.
.TP
.B \-vpt\fR, \fB\-vot\fR, \fB\-vpp\fR, \fB\-vop\fR, \fB\-vpi\fR, \fB\-voi\fR, \fB\-vpf\fR, \fB\-vof\fR
These options show individual graphs associated
with the
.I sar\fR(1)
option
.B \-v\fR.
The first letter is derived from the equivalent
option in
.I sar\fR(1),
the second letters stand for
.I percentage
and
.I overflow
and the third letters stand for
.I text\fR,
.I process\fR,
.I inode
and
.I file\fR.
.TP
.B \-m
This option shows the graphs associated with
the
.I sar\fR(1)
option
.B \-m\fR.
.TP
.B \-mcm\fR, \fB\-mcs\fR
These options show individual graphs associated
with the
.I sar\fR(1)
option
.B \-m\fR.
The first letter is derived from the equivalent
option in
.I sar\fR(1),
the second letter stands for
.I call
and the third letters stand for
.I msgrcv()
and
.I semop()\fR.
.PD
.br
.ne 5
.SH DIAGNOSTICS
Most of the messages produced by 
.I sarplot
are self-explanatory, those that are not
are described here:
.PD 0
.TP 25
.B sarplot: INTERNAL ERROR: no code yet for x axis with graph factor > 604800
.I sarplot
currently will plot a maximum of 1 week per page, i.e. 604800 seconds.
If longer periods are required on a single page then the
.I sarplot
program must be modified.
.br
.ne 5
.PD
.SH WARNINGS
There is a limit of eight graphs lines per page, this is 
a limit imposed by 
.I gnuplot\fR(1).
For this reason,
.I sarplot
does not have a
.B \-A
option as does 
.I sar\fR(1).
.PP
.I Sarplot
is quite slow loading data; setting the verbosity level to 
4 may provide assurances that the program is actually doing 
something.
.PP
The maximum values for any graph have only been very roughly
set by the author. It is envisaged that these will be adjusted
over time. Probably the best method is to set them to the 
maximum values ever encountered on a functional system. If a 
new maximum is encountered then the maximum value with
.I sarplot
should be adjusted. If a smaller value is encountered, no matter
if it is the norm or not, then the maximum value defined in
.I sarplot
should not be adjusted.
.br
.ne 5
.SH FILES
.PD 0
.TP 25
.B /tmp/sarplot\fIPID\fB.unzsarfile
Temporary copy of uncompressed
.I sar\fR(1)
files, if the original was compressed.
.TP 25
.B /tmp/sarplot\fIPID\fB.plotdata.\fIGRAPHID\fB
Temporary file used to store numeric data for a particular 
graph; this will be fed to
.I gnuplot\fR(1)
and then deleted.
.TP 25
.B /usr/adm/sa/sa[0-9][0-9]
usual place for 
.I sar\fR(1)
files, although
.I sarplot
requires that any pathnames supplied on the command line are
explicit.
.PD
.br
.ne 5
.SH ENVIRONMENT VARIABLES
.PD 0
.TP 25
.B PATH
Used to locate various external programs.
.TP 25
.B DISPLAY
Used to direct 
.I gnuplot\fR(1)
where to display its graphs.
.PD
.br
.ne 5
.SH SEE ALSO
compress(1), 
gnuplot(1), 
gzip(1), 
lp(1), 
sar(1), 
xhost(1),
X(1), 
exec(2), 
fork(2), 
iget(2), 
lookuppn(2), 
msgrcv(2), 
read(2), 
write(2), 
semop(2), 
canon(3)
.br
.ne 5
.SH STATUS
Very unstable!
.br
.ne 5
.SH AUTHOR
Alexis Huxley <alexis@danae.demon.co.uk>
.br
.ne 5
.SH BUGS
Doubtlessly numerous; this program has not been properly tested.
.br
.ne 5
.SH FUTURE DEVELOPMENT
Support should be added for devices other than X windows and Postscript printers. 
This would be trivial, since 
.I sarplot
only instructs
.I gnuplot\fR(1)
to produce output for a specific device and
.I gnuplot\fR(1)
already supports many devices.
.PP
In reality, most of the time the user will want to display specific 
combinations of graphs. Options could be added to produce these specific 
combinations.
.PP
Those sections of 
.I sarplot
which pertain to specific operating systems should be abstracted, to
facilitate easy porting. The same is true for those sections of the code
that deal with specific versions of 
.I sar\fR(1) 
and 
.I gnuplot\fR(1).
.PP
The execution speed could be improved, primarily be increasing the 
data file load speed.
.PP
The maximum values that the top of the graph represents for each graph
plotted are not displayed on the graph. These should ideally be included
in the graph key. Actually labeling the Y axis would result in the
the labels overwriting each other.
.PP 
The text of the graph titles only roughly correlates with the
column headings produced by
.I sar\fR(1).