TREND(1)                  BSD General Commands Manual                 TREND(1)

NAME
     trend — a general-purpose, efficient trend graph

SYNOPSIS
     trend [-dDSsvlmFgGhtAERIMNTLzfcpue] [-display] [-geometry] [-iconic]
           ⟨fifo | -⟩ ⟨hist-spec | hist-sz x-sz⟩ [low high]

DESCRIPTION
     trend is a general-purpose, efficient trend graph for "live" data. Data
     is read in ASCII form from a file or continuously from a FIFO and dis‐
     played in real-time into a multi-pass trend (much like a CRT oscillo‐
     scope).  trend can be used as a rapid analysis tool for progressive or
     time-based data series together with trivial scripting.

     trend requires at least a valid fifo to read from and an history specifi‐
     cation (hist-spec) or, for advanced usage, a combination of history size
     and horizontal size (hist-sz and x-sz respectively). Optionally, to dis‐
     able auto-scaling, the vertical limits can be specified directly through
     the command line via low and high.  The default input format is ASCII, in
     absolute counting mode. Many settings can be changed directly during exe‐
     cution.

INPUT
   FIFO
     To display real-time data you should use a FIFO. Both standard input and
     named pipes can be used. Standard input (used for simple pipelining pur‐
     poses) can be opened by using - instead of a named file. A named FIFO can
     be created using the mkfifo(1) command. FIFOs are automatically re-opened
     upon EOF. See the EXAMPLES section.

     Alternatively you can store your data in a plain file and simply display
     its last values non-interactively.

     When new data is written, the value is plotted and the cursor position is
     advanced. That is, the graph scrolling speed is determined by the speed
     of the data flow. When the number of received values is above the speci‐
     fied horizontal size, the graph will wrap or scroll, depending on your
     settings.

   ASCII DATA
     The default data format is a space/tab/newline-separated series of
     parseable ASCII numbers; eg:

           1 2 3 4 5.1 0642
           0x12 -12.4E5 .987

     The parser is very lenient, and will silently ignore whatever looks like
     garbage.

   COUNTING MODES
     By default all input values are considered absolute and displayed "as is"
     in a single graph.

     The -c [N]mode flag sets an alternate counting mode and the number of
     available graphs.  Available modes are:

           a    absolute (default)
           i    incremental counter
           d    differential values

     In incremental and differential mode, each value is calculated using the
     previous value as a reference except for the first, which is taken as
     absolute. The number of graphs can be specified by prefixing a multiplier
     before the counting mode (eg: 2a draws two graphs in absolute mode). See
     MULTIPLE GRAPHS for more details on how this affects the input stream.

   FORMAT TYPES
     Different input formats are supported, as specified by the -f flag. Note
     however that only the ASCII parser (the default) silently ignores errors.
     NaNs and Infinity have special treatment. Internally, trend always works
     with double precision floating points: conversion toward these is per‐
     formed with the default FPU conversion rules. The actual underlying
     binary format depends on the host architecture:

           a    ASCII parser (default)
           f    binary float
           d    binary double
           s    binary short
           i    binary int
           l    binary long

   SPECIAL VALUES
     ASCII and binary floating point input have special treatment for NaNs and
     Infinity (entered in any representable form). Both are considered as
     "undefined values". Undefined values can be highlighted, but aren't oth‐
     erwise rendered. If the -e flag is set, Infinity enters an escape
     sequence instead (See ESCAPE SEQUENCES)

   MULTIPLE GRAPHS
     Multiple graphs can be displayed inside a single trend instance by speci‐
     fying a prefix number N for the -c flag. The input is interleaved, but
     otherwise unchanged: the reference value, if needed, is expected to be
     seen N times, one for each graph. Thus, for three graphs (A, B and C),
     the input order is:

           [A0 B0 C0]
           A1 B1 C1
           A2 B2 C2
           .. .. ..

     The display is updated only once all graph values are read. The color,
     label and origin for each graph can be specified through the usual com‐
     mand-line flags, separating each value with a comma; in the same order as
     the input. Default colors and labels are assigned if not completely spec‐
     ified.

     All graphs share and are affected by the same settings, except for the
     origin (zero) which can be changed independently. Filling, values and the
     examiners only work on the current graph. The current graph can be cycled
     dynamically with the TAB key and differentiated using the K key, which
     cycles between "normal", "dim others" and "hide others" views. The graph
     key, if enabled, also highlights the current graph.

   ESCAPE SEQUENCES
     If escape sequences are enabled (through the -e flag), entering Infinity
     (in any representable form) will start an escape sequence. Currently,
     this feature is not yet implemented: Infinity is simply discarded. This
     is reserved for future use as a way to control the trend interface and
     parameters remotely.

OPTIONS
   FLAGS
     -d                       "dimmed" shading mode
     -D                       visible distribution graph
     -S                       enable anti-aliasing
     -s                       "scrolling" mode
     -v                       visible values
     -l                       visible visual/max sync latency
     -m                       visible marker
     -F                       enable filling
     -g                       visible grid
     -G grid-spec             specify grid resolution
     -z zero[,zero...]        specify y zero/s
     -h                       help and version info
     -t str                   specify a window title
     -A colour                background colour
     -E colour                text (values) colour
     -R colour                grid colour
     -I colour[,colour...]    trend colour/s
     -M colour                marker colour
     -N colour                interactive examiner colour
     -T colour                edit mode colour
     -L label[,label...]      trend label/s
     -c mode                  input number/counting mode (See COUNTING MODES)
     -f format                input format (See FORMAT TYPES)
     -p rate                  polling rate (hz)
     -u                       show undefined values
     -e                       enable escape sequences (See ESCAPE SEQUENCES)
     -display                 See X(7).
     -geometry                See X(7).
     -iconic                  See X(7).

   HIST-SPEC
     An history specification is another convenient form of defining the pair
     `hist-sz x-sz` for common cases. An history specification can be in
     either one of the following formats:

           N      Sets x-sz to N, and hist-sz to N+1.
           N/M    Sets hist-sz to N, and x-sz to N/M.
           NxM    Sets x-sz to N, and hist-sz to N*M.

     While this may seem hard at first, trend fifo '60x3' is an easier way of
     expressing "60 seconds for 3 minutes" and similar idioms.

   COLOUR
     A colour is specified in hex RGB format, as follows: #RRGGBB, RRGGBB or
     0xRRGGBB; some examples:

           #FF0000    red
           #00FF00    green
           #A020F0    purple

   GRID-SPEC
     A grid specification is of the form:

           [[A][+C]][x[B][+C]]

     (eg: 1.3, 10+5, 1x10+5, +5x+5; +1x+1 gets the old behaviour) where:

           A    y grid resolution
           B    x grid resolution
           C    draw a mayor line every C normal grid lines

DISPLAY
   INTERACTIVE KEYS
           ESC      quit/exit
           TAB      cycle current graph
           a        toggle auto-scaling
           A        re-scale the graph without activating auto-scaling
           d        toggle dimmed shading mode
           D        toggle distribution graph
           S        toggle anti-aliasing
           s        switch scrolling mode (wrap-around or scrolling)
           v        toggle values
           l        show visual and maximal sync latency
           L        set limits interactively
           m        activate a marker on the current cursor position
           f        toggle filling
           g        toggle grid
           G        change grid-spec interactively
           z        change zero interactively
           Z        set limits by center and amplitude
           p        change polling rate interactively
           u        toggle display of undefined values
           k        toggle the graph key
           K        cycle view mode (normal, dim others or hide others)
           space    pause visualisation (but still continue to consume input
                    to preserve time coherency)

   AUTOSCALING
     When autoscaling is enabled the graph will be scaled vertically to fit
     visible values. The grid resolution is used to add some vertical bounds
     to the graph. Disabling autoscaling interactively will retain current
     limits. When the grid is too dense to be displayed it's deactivated auto‐
     matically.

   LATENCY INDICATOR
     The latency indicator shows a 5s average of the visual and maximal sync
     latency (in seconds). The visual latency is the time-frame between real
     value updates and the final output you're seeing: it includes copy/redraw
     times, which varies depending on enabled layers, plus video sync. The
     maximal sync latency is the maximal time ever required for any received
     value to be synced with the display: since the display is updated atomi‐
     cally, values received while redrawing are implicitly delayed. See the
     UPDATE POLICY section for further details.

   SHADING MODES
     The default is to shade uniformly old values to complete transparency.
     The "dimmed" shading mode draws the foreground values with full opacity
     and the others with half opacity.

   SCROLLING MODES
     The default visualisation mode is "wrap-around": newer values will simply
     wrap around the screen when new data arrives. The other available one is
     "scrolling": new data is always placed at the right edge of the screen,
     and older values scrolled on the left.

   VALUE INDICATORS
     Three value indicators are drawn on the screen: upper limit, lower limit
     and current value (respectively on the upper right, lower right and lower
     left of the screen).

   INTERACTIVE EXAMINERS
     You can query interactively the graph for any value in the history by
     clicking with the first mouse button. This will enable a permanent exam‐
     iner in the selected position and display up to the three nearest values
     in the upper-left corner of the screen. Intersections are projected hori‐
     zontally, while a small circle will show the position of the nearest sam‐
     pled value. The mean value refers to the three intersections.

     By holding down the CTRL key while clicking/dragging only "foreground"
     values will be considered.

     When clicking inside the distribution graph, the current count for the
     selected value is displayed instead.

     The examiners can be removed by clicking anywhere with the third mouse
     button.

   DISTRIBUTION GRAPH
     D or -D enable a distribution graph on the left side of the window. This
     is especially useful when analyzing the continuity of a function or sig‐
     nal. Intensity is proportional to the visible maximum.

   FILLING
     f or -F enable filling. In standard mode, or when hist-sz is smaller than
     x-sz, the area between the curve and zero will be filled. Otherwise, in
     dimmed mode, the area between the "foreground" and "background" values is
     filled instead.

UPDATE POLICY
     The fifo is read and managed asynchronously from the graphics. Delays at
     the display end will not interfere with the data feed.

     The fifo is unbuffered and the feeder thread is synchronously locked on
     it waiting for new data.

     The value is put in the history buffer when a separator character is
     received after the value, or, for binary input, when the needed amount of
     bytes is read (in this case each value is read with a single read call).

     The polling rate (as defined by p or -p and defaulting to 1000) defines
     how often the history buffer should be checked for updates and kept in
     sync with the visual. Values greater than 1000 result in continuous scan‐
     ning (note that this only affects the maximal sync latency, and not the
     display rate, which is handled automatically).

     Syncing occurs atomically, reflecting the actual state at the instant of
     the update. Scheduler latencies apply.

ENVIRONMENT
     DISPLAY See X(7).

EXAMPLES
     Running trend with a named FIFO:

           mkfifo fifo
           command > fifo &
           trend fifo ...

     Display the number of current active processes over time:

           (while true; do ps -A | wc -l; sleep 1; done) | \
           trend - 60x24

     Display two graphs:

           trend -c2a -L"graph 1, graph 2" fifo ...

DIAGNOSTICS
     The trend utility exits 0 on success, and >0 if an error occurs.

ERRORS
     trend: producer thread exiting  The data stream finished for some reason
     (the specified file was invalid at the time of the request). For regular
     or invalid files this warning is normal.

SEE ALSO
     mkfifo(1), stdin(4), fd(4), /usr/share/doc/trend/examples/

AUTHORS
     trend is distributed under LGPL (see COPYING) WITHOUT ANY WARRANTY.
     Copyright(c) 2003-2009 by Yuri D'Elia <wavexx@thregr.org>.

                               November 2, 2007