<HTML
><HEAD
><TITLE
>Customization</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.54"><LINK
REL="HOME"
TITLE="gstripchart"
HREF="index.html"><LINK
REL="PREVIOUS"
TITLE="Using gstripchart"
HREF="usage.html"><LINK
REL="NEXT"
TITLE="Known bugs and limitations"
HREF="bugs.html"></HEAD
><BODY
CLASS="SECT1"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>gstripchart</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="usage.html"
>&#60;&#60;&#60; Previous</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="bugs.html"
>Next &#62;&#62;&#62;</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="PREFS"
>Customization</A
></H1
><P
>The <TT
CLASS="APPLICATION"
>gstripchart</TT
> program
    determines the parameters to display by reading a configuration
    file.  The <TT
CLASS="APPLICATION"
>gstripchart</TT
> program will
    look for a configuration file in the following order:
    <P
></P
><UL
><LI
><P
>first, for a file specified on the command
      line, </P
></LI
><LI
><P
>then, for a file named
      <TT
CLASS="FILENAME"
>gstripchart.conf</TT
> in the current working
      directory, </P
></LI
><LI
><P
>then, for a file named
      <TT
CLASS="FILENAME"
>.gstripchart.conf</TT
> in the users home
      directory, </P
></LI
><LI
><P
>then, for a file named
      <TT
CLASS="FILENAME"
>/etc/gstripchart.conf</TT
>, </P
></LI
><LI
><P
>and finally, for a file named
      <TT
CLASS="FILENAME"
>gstripchart.conf</TT
> in the
      <TT
CLASS="REPLACEABLE"
><I
>CONFDIR</I
></TT
> directory, which will usually
      be either <TT
CLASS="FILENAME"
>/usr/share/gstripchart/</TT
> or
      <TT
CLASS="FILENAME"
>/usr/local/share/gstripchart/</TT
>.
      </P
></LI
></UL
>

    If no configuration file is found, the program displays an error
    message and exits.</P
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="OPTIONS"
>Options</A
></H2
><P
>There are a few command line switches that can be used to
      alter the behavior of the program.  In addition to the common
      help, usage, version, Gnome, Gtk, and Session management
      options, the following gstripchart-specific options are
      available:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>&#8211;&#8211;geometry
	    <TT
CLASS="REPLACEABLE"
><I
>GEOMETRY-SPEC</I
></TT
></DT
><DD
><P
>A standard X11 geometry specification of the form
	    <TT
CLASS="REPLACEABLE"
><I
>WxH±X±Y</I
></TT
>. </P
></DD
><DT
>&#8211;&#8211;config-file
	    <TT
CLASS="REPLACEABLE"
><I
>FILENAME</I
></TT
></DT
><DD
><P
>Specifies a file from which to read configuration
	    information, overriding the normal configuration file
	    search order described in <A
HREF="prefs.html"
>the section called <I
>Customization</I
></A
>.</P
></DD
><DT
>&#8211;&#8211;chart-interval
	    <TT
CLASS="REPLACEABLE"
><I
>UPDATE-INTERVAL</I
></TT
>, &#8211;&#8211;slider-interval
	    <TT
CLASS="REPLACEABLE"
><I
>UPDATE-INTERVAL</I
></TT
></DT
><DD
><P
>Specifies the time interval in seconds between
	    updates to the chart window and slider window.  If
	    unspecified, the chart window will be updated every 5
	    seconds and the slider window will be updated every 0.2
	    seconds. </P
></DD
><DT
>&#8211;&#8211;chart-filter
	    <TT
CLASS="REPLACEABLE"
><I
>TIME-CONSTANT</I
></TT
>, &#8211;&#8211;slider-filter
	    <TT
CLASS="REPLACEABLE"
><I
>TIME-CONSTANT</I
></TT
></DT
><DD
><P
>Specifies the time constant in seconds to be used
	    in low-pass filtering the data displayed in the chart or
	    slider windows.  A time constant of 0 seconds turns
	    low-pass filtering off, which can result in a jumpy
	    display.  A time constant in the same range as the
	    interval parameter, described above, is usually a good
	    choice.  Much larger values cause display updates to
	    become sluggish.  If unspecified, no low pass filtering is
	    performed in either window. </P
></DD
><DT
>&#8211;&#8211;menubar</DT
><DD
><P
>Adds an application menu bar to the main window.
	    Normally this is omitted, and the menu is popped up by
	    right-clicking on the chart window. </P
></DD
><DT
>&#8211;&#8211;omit-slider</DT
><DD
><P
>Causes the display of the slider window to be
	    suppressed. </P
></DD
><DT
>&#8211;&#8211;display-type
	    <TT
CLASS="REPLACEABLE"
><I
>TYPE</I
></TT
></DT
><DD
><P
><TT
CLASS="REPLACEABLE"
><I
>TYPE</I
></TT
> specifies the type
	      of display to be generated.  The
	      <TT
CLASS="REPLACEABLE"
><I
>TYPE</I
></TT
> specifier can be one of:
	      </P
><P
></P
><UL
><LI
><P
>gtk &#8212; use the default gtk-based
	      graphic display; </P
></LI
><LI
><P
>applet &#8212; run as an applet in the
	      Gnome panel. </P
></LI
></UL
></DD
></DL
></DIV
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="CONFIG"
>Configuration File</A
></H2
><P
>The behavior of the
      <TT
CLASS="APPLICATION"
>gstripchart</TT
> program is determined by
      the contents of the configuration file that it reads at startup.
      This file is located as described in <A
HREF="prefs.html"
>the section called <I
>Customization</I
></A
>
      </P
><P
>This configuration file contains a series of optional
      application-wide configuration options described in <A
HREF="prefs.html#APP-OPTS"
>the section called <I
>Application-Wide Configuration Options</I
></A
>, followed by a series of parameter
      configuration options described in <A
HREF="prefs.html#PARAM-OPTS"
>the section called <I
>Parameter Configuration Options</I
></A
>, one for each parameter to be plotted.  Each of these
      configuration file lines is comprised of RFC-822 style
      "keyword: value" pairs.  A comment can be included anywhere
      within the configuration file by putting a sharp sign (#) in the
      first column of each comment line, and blank lines can be used
      wherever they will improve readability. </P
><P
>Here's an example of the initial portion of a
      <TT
CLASS="APPLICATION"
>gstripchart</TT
> configuration file.  It
      begins (as all files should) with a comment describing the
      purpose of the file.  The comment is followed by three
      application-wide configuration options.  The first sets the
      chart interval to 5.000, so that the "strip" portion of the
      display is updated every 5 seconds.  Next, the minor tick
      interval is set to 12 chart update periods, producing a minor
      tick mark on the display at one-minute intervals.  Finally, the
      major tick interval is set to 5 minor tick periods, producing a
      major tick mark on the display at five-minute intervals. </P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>&#13;#
# gstripchart.conf --
#   an example configuration file 
#   for the GNOME stripchart program.
#

chart-interval:		5.000

minor_ticks:		12
major_ticks:		5</PRE
></TD
></TR
></TABLE
><P
>The following application-wide configuration option
      keywords are available.  Some are optional; some are only used
      by certain display types; many have reasonable default values,
      as described below. </P
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="APP-OPTS"
>Application-Wide Configuration Options</A
></H3
><P
>The first group of keywords provide the same functions as
	the command line switches described in the previous section.
	The options in this group must be placed at the beginning of the
	configuration file, prior to the parameter definition section.
	If a value is supplied for any of these parameters both in the
	configuration file and on the command line, the command line
	value takes precedence. </P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>chart-interval: <TT
CLASS="REPLACEABLE"
><I
>UPDATE-INTERVAL</I
></TT
>, slider-interval: <TT
CLASS="REPLACEABLE"
><I
>UPDATE-INTERVAL</I
></TT
></DT
><DD
><P
>Specifies the time interval in seconds between
	      updates to the chart window and slider window as described
	      previously under <A
HREF="prefs.html#OPTIONS"
>the section called <I
>Options</I
></A
>. </P
></DD
><DT
>chart-filter: <TT
CLASS="REPLACEABLE"
><I
>TIME-CONSTANT</I
></TT
>, slider-filter: <TT
CLASS="REPLACEABLE"
><I
>TIME-CONSTANT</I
></TT
></DT
><DD
><P
>Specifies the time constant in seconds to be used
	      in low-pass filtering the data displayed in the chart or
	      slider windows as described previously under <A
HREF="prefs.html#OPTIONS"
>the section called <I
>Options</I
></A
>. </P
></DD
><DT
>menu: <TT
CLASS="REPLACEABLE"
><I
>YES-OR-NO</I
></TT
></DT
><DD
><P
>Adds or omits an application menu bar to the main
	      window.</P
></DD
><DT
>slider: <TT
CLASS="REPLACEABLE"
><I
>YES-OR-NO</I
></TT
></DT
><DD
><P
>Adds or omits the "pen" display to the main window.
	      </P
></DD
><DT
>minor_ticks: <TT
CLASS="REPLACEABLE"
><I
>INTERVAL-COUNT</I
></TT
></DT
><DD
><P
>Sets the number of pixels (update intervals)
	      between minor tick marks on the gtk and applet displays.
	      </P
></DD
><DT
>major_ticks: <TT
CLASS="REPLACEABLE"
><I
>INTERVAL-COUNT</I
></TT
></DT
><DD
><P
>Sets the number of pixels (update intervals)
	      between major tick marks on the gtk and applet displays.
	      </P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="PARAM-OPTS"
>Parameter Configuration Options</A
></H3
><P
>The second portion of the
	<TT
CLASS="APPLICATION"
>gstripchart</TT
> configuration file
	contains a series of parameter description groups, one group
	for each parameter to be plotted.  Each parameter group is
	made up of a "begin" and "end" pair of lines enclosing the
	remaining parameter definition lines.  In addition to the
	"begin" and "end" statements, each parameter group must
	contain an equation statement, which determines the value to
	be displayed, and either a "color" or a "lights" statement,
	which determines the display format for the parameter. </P
><P
>For example, a very minimal parameter definition would
	be the following system load average parameter. </P
><P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>&#13;# Load -- display the system one minute load average

begin:		Load
  color:	yellow
  equation:	$load_1m
end:		Load</PRE
></TD
></TR
></TABLE
> </P
><P
>The following keywords are available to be used to
	define the way that a parameter is displayed. </P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>begin: <TT
CLASS="REPLACEABLE"
><I
>[ PARAMETER-NAME ]</I
></TT
>, identifier: <TT
CLASS="REPLACEABLE"
><I
>[ PARAMETER-NAME 
              ]</I
></TT
></DT
><DD
><P
>Introduces a parameter definition, and assigns a
	      name to the parameter.  This line
	      <I
CLASS="EMPHASIS"
>must</I
> be the first line of a
	      parameter description.  The "begin" and "identifier"
	      keywords are synonymous. The
	      <TT
CLASS="REPLACEABLE"
><I
>PARAMETER-NAME</I
></TT
> is optional,
	      but if supplied must match the
	      <TT
CLASS="REPLACEABLE"
><I
>PARAMETER-NAME</I
></TT
> used in the
	      corresponding "end" statement. </P
></DD
><DT
>end: <TT
CLASS="REPLACEABLE"
><I
>[ PARAMETER-NAME ]</I
></TT
></DT
><DD
><P
>Closes a parameter block introduced by the
	      "begin" or "identifier" keyword. The
	      <TT
CLASS="REPLACEABLE"
><I
>PARAMETER-NAME</I
></TT
> must match any
	      <TT
CLASS="REPLACEABLE"
><I
>PARAMETER-NAME</I
></TT
> supplied in
	      the corresponding "begin" statement. </P
></DD
><DT
>equation: <TT
CLASS="REPLACEABLE"
><I
>STRING</I
></TT
></DT
><DD
><P
>An equation used to obtain the value to be plotted
	      for this parameter. </P
><P
>A value is obtained by evaluating the "equation"
	      line using these field values.  The first (or only)
	      value is denoted by $1, the next by $2, and so forth.
	      The difference between the field values between the last
	      and the current iteration is denoted by ~1, ~2, and so
	      forth.  The elapsed time in seconds between the last and
	      current iteration is ~t.  The requested update interval
	      is $i, and the delta (which will always be zero) is
	      ~i.</P
><P
>The usual infix arithmetic operators &#8212;
	      addition (+), subtraction (-), multiplication (*),
	      division (/), and remaindering (%) &#8212; are
	      available, along with parenthesis for grouping
	      subexpressions. </P
></DD
><DT
>color: <TT
CLASS="REPLACEABLE"
><I
>COLOR-NAME</I
></TT
></DT
><DD
><P
>Determines the color to be used in displaying a
	      parameter.  The color names and their RGB values are
	      taken from X11/rgb.txt. </P
></DD
><DT
>filename: <TT
CLASS="REPLACEABLE"
><I
>FILENAME</I
></TT
></DT
><DD
><P
>The file from which a parameter value is read.
	      When a filename beginning with a "|" is supplied, input
	      lines will be read from a pipe. </P
><P
>On each iteration, a value to be displayed is
	      obtained for each parameter in the configuration file.
	      The file named in the "filename" line is opened --
	      either as a pipe if the filename begins with a pipe
	      character ( | ), or as a regular file otherwise -- and a
	      line is read. </P
><P
>If a pattern was specified, lines are read until
	      one is found that contains the pattern string anywhere
	      in the line.  This line is split into a series of
	      whitespace separated fields, each of which is
	      interpreted as a floating point number. </P
></DD
><DT
>lights:
	      <TT
CLASS="REPLACEABLE"
><I
>COLOR-NAME [, COLOR-NAME...]</I
></TT
></DT
><DD
><P
>If a parameter block contains a "lights:" line
	      instead of a "color:" line, the parameter will not be
	      plotted.  Rather, a small square in one of the supplied
	      colors is displayed near the upper-left corner of the
	      display.  The color used is based on the value of the
	      parameter.  A value of less that 0.5 leaves the light in
	      the background color; a value between 0.5 and 1.5
	      displays a light in the first color; a value between 1.5
	      and 2.5 displays a light in the second color; and so
	      forth for as many colors were supplied on the "lights:"
	      line. </P
></DD
><DT
>pattern: <TT
CLASS="REPLACEABLE"
><I
>STRING</I
></TT
></DT
><DD
><P
>The pattern which identifies the line from which
	      a parameter value is to be extracted.  If no pattern is
	      provided, the first line of the file is used. </P
></DD
><DT
>scale: <TT
CLASS="REPLACEABLE"
><I
>LOG-OR-LINEAR</I
></TT
></DT
><DD
><P
>Specifies whether a logarithmic or linear scale
	      factor is to be used when plotting a parameter value. </P
></DD
><DT
>maximum: <TT
CLASS="REPLACEABLE"
><I
>NUMBER</I
></TT
></DT
><DD
><P
>The largest value that can be displayed.  Any
	      value in excess of the maximum will be plotted at the
	      top of the display.  If omitted, a default value of 1.0
	      is used. </P
></DD
><DT
>minimum: <TT
CLASS="REPLACEABLE"
><I
>NUMBER</I
></TT
></DT
><DD
><P
>The smallest value that can be displayed.  Any
	      value less than the minimum will be plotted at the
	      bottom of the display.  If omitted, a default value of
	      0.0 is used.  </P
></DD
><DT
>active: <TT
CLASS="REPLACEABLE"
><I
>YES-OR-NO</I
></TT
></DT
><DD
><P
>If a parameter is marked "active: no", it will
	      not be displayed.  This provides a convenient way to
	      disable a parameter without deleting it from a parameter
	      file. </P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="LIBGTOP"
>libgtop Values</A
></H3
><P
>Normally, the <TT
CLASS="APPLICATION"
>gstripchart</TT
>
	program will be built with the libgtop library linked in.  The
	libgtop library provides a portable and well-standardized
	method of accessing common system performance parameters.
	This is the preferred method of obtaining a value to be
	plotted.</P
><P
>The following libgtop parameters are available: </P
><P
></P
><UL
><LI
><P
>CPU Statistics &#8212; cpu_total,
	    cpu_user, cpu_nice, cpu_sys, cpu_idle, and cpu_freq
	    </P
></LI
><LI
><P
>Memory Statistics &#8212; mem_total,
	    mem_used, mem_free, mem_shared, mem_buffer, mem_cached,
	    mem_user, mem_locked </P
></LI
><LI
><P
>Swap Statistics &#8212; swap_total,
	    swap_used, swap_free, swap_pagein, swap_pageout </P
></LI
><LI
><P
>Uptime Statistics &#8212; uptime, idletime
	    </P
></LI
><LI
><P
>Loadavg Statistics &#8212; load_running,
	    load_tasks, load_1m, load_5m, load_15m </P
></LI
><LI
><P
>Network Statistics &#8212; net_pkts_in,
	    net_pkts_out, net_pkts_total, net_bytes_in, net_bytes_out,
	    net_bytes_total, net_errs_in, net_errs_out, net_errs_total
	    </P
><P
>Note that the network statistic values don't use the
	    libgtop library.  Instead, they are read directly from
	    /proc/net/dev, and so are only available under
	    Linux. </P
></LI
></UL
><P
>These are all signed long integer quantities, except
	for uptime, idletime, and the five load values which are
	floating point values. </P
></DIV
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="usage.html"
>&#60;&#60;&#60; Previous</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="bugs.html"
>Next &#62;&#62;&#62;</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Using gstripchart</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
>&nbsp;</TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Known bugs and limitations</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>