floyd

FLOYD(1)                    General Commands Manual                   FLOYD(1)

NAME
     floyd — display system load via p*u*l*s*e of PC keyboard LED

SYNOPSIS
     floyd [-N|-C|-S] [-h|-H] [-l <msec>] [-m <msec>] [-u <sec>] [-s <msec>]
           [-b <LA>] [-a <1|5|15>] [-/+p] [-i <interface>] [-/+E] [-/+t]
           [-/+v] [-/+d] [-D|--] [-F] [ttydevice]
     wywh [-s] — equivalent to floyd -E [options]
     tfloyd [options] — equivalent to floyd -t [options]

VERSION
     Version 1.3.x
     Version 2.0.x

DESCRIPTION
     Floyd blinks PC keyboard LED with an interval which varies depending upon
     the system's load average.

     The LED is assumed to be equipped on the keyboard corresponding to its
     standard input, which is normally a virtual console (VC) you are using.
     If a device file such as /dev/tty1 is specified as an argument ttydevice,
     the device file is used instead of standard input.  Currently, the last
     device file specified in the command line is recognized as the target
     device.

     Floyd does not affect the keyboard status flag corresponding to the LED.
     That is, you can use the modifier key corresponding to the blinking LED
     (eg. CapsLock), even while the LED is blinking: you just can't see the
     modifier key status through the LED.

     By default, with no invoking option specified, floyd operates in `load
     average' mode, in which LED blinking interval is determined by current
     load average.  The blinking interval (off duration) is calibrated about
     200msec (plus fixed delay: see option -s described below) at load average
     1.0.  Actual blinking interval is derived by dividing the interval at
     load average 1.0 (see option -l) with the current load average read from
     /proc/loadavg.  The maximum blinking interval does not exceed 1 second by
     default (see option -m; in current version, the maximum value has nothing
     to do with the length of the rumoured crotchet in a certain tune).  The
     on duration of the LED is fixed about 100msec in lower load, and 50msec
     in higher load (approx. 8.5) range.

     Another operating mode of floyd is `packet load' mode, in which the
     current packet traffic of a network interface is displayed through a
     keyboard LED.  The packet traffic is derived from /proc/net/dev (see
     option -p, -i, and -E).

     If floyd should be run in background, use `&' suffix from shell, or
     option -D in non-PTHREAD version, or -F in PTHREAD version (see below).

     Floyd surely turns LED off only when killed by a signal SIGINT, SIGTERM,
     or SIGHUP.  You may have to setup LED(s) again with setleds(1) after
     killing floyd with other signals.

     Some of the constants controlling blinking behaviour can be adjusted by
     options described below.

COMMAND LINE ARGUMENTS
     Command line arguments are parsed from the left to right.  An `option' is
     a command line argument starting with + or -, and should contain one or
     more option character, to which an optional argument for it may follow.
     The option can be specified in -Nv, or -N -v manner but an option
     requiring an argment cannot be specified in the middle of one argument.
     For example, -vs20 is correct but -vs20NE is not. Perhaps NE part is
     ignored in this case.  If a command line argument neither starts with +
     or -, nor being an argument to any option, the argument is recognized as
     a device file name of the virtual console which floyd should control.

     Options can be specified even after a device file argnument.  Any number
     of device filename can be specified, but currently the last one is used
     as target.  Similarly if the same option is specifid more than onece, the
     last one is recognized.  A facility corresponding to binary option
     character such as E|t|v|d can be disabled with a character `+' as in
     sh(1).  The disabling with `+' is convenient in detatching a child
     process, or launching a thread (if your floyd biniary has PTHREAD
     support).  There may be some other undocumented options.  Also refer to
     the source files, or attached documents.

     -N|-C|-S
             The option -N , -C , or -S each specifies LED to blink as being
             NumLock, CapsLock, or ScrollLock. Without any of these options, a
             default LED selected with compiling option is used.  Perhaps
             CapsLock LED is the default.

     -h      Print `usage' string to standard output and exit with status 0.

     -H      Print version number to standard output and exit with status 0.

     -/+p    Enable (or disable) `packet load mode', in which packet traffic
             derived from /proc/net/dev is displayed via LED.  Namely, the
             status of the NIC LED (normally equipped at the backside in most
             desktop PC) is copied to the keyboard LED.  The interface to be
             watched by floyd can be specified by option -i.  below.  If the
             network is not explicitly specified, eth0 is used.  Unless sleep
             value is explicitly specified with -s option, the sleep is
             automatically set to default value for this mode.  All the other
             options taking a numeric argument other than -s have no effect in
             the packet load mode.

     -i <interface>
             Specify the name of network interface to be watched in packet
             load mode.  No effect in non-packet-load mode (just gracefully
             ignored).

     -/+E    Equivalent to -p -i eth0, or just -p.

     -/+t    Text mode.  Keyboard LEDs do not blink at all, but a virtual LED
             expression by ASCII character `*' is blinked on standard error
             output.  Uses no ncurses. So terminal should know how to deal
             with carriage return character. It may be useful if the hardware
             lacks keyboard LED.

     -/+v    Enable display of initial control parameters (constants) on
             startup.  It may be useful in tuning LED blinking for a
             particular system.

     -/+d    Enable debug mode. This is rather an expert, or developper-only
             sort of.  Enables printing debug info on some control variables,
             or program/system status.  Some information printing enabled by
             -/+d may be more verbose with -/+v.

     --      Works as an alias of -D below.

     -D      Defines a floyd `job'.  The present floyd control parameters
             modified by the options from the first option or the option
             following the last occurrence of -D to the relevant -D defines a
             job, which normally controls a particular LED in a particular
             operating mode (the load average mode, or packet load mode).

             The defined `job' is executed as a child process if floyd is
             compiled without PTHREAD support, or as a thread if floyd is
             compiled with PTHREAD support.  In non-PTHREAD version of floyd,
             the child process corresponding to the defined job is immediately
             forked on reading -D, while in PTHREAD version, all the defined
             job are stored in a linked list, and then they are run as
             threads.  If there is any argument is left after the last -D, a
             job defined by the remaining parameters are executed by the
             parent (master) process.  For example,

                   $ floyd -EC -D  +E -Sa 15 -D  -Nva1
              defines two jobs which should be run as a child process or a
             thread, and a job which should be done by the parent (master)
             process.  The first job uses Capslock (C) LED in packet load mode
             (E), the second job uses ScrollLock (S) LED in load average (over
             15min) mode, and the last job uses Numlock (N) LED in the verbose
             (v) load average (over 1min) mode.

             In PTHREAD version, only one child process can be forked by an
             option -F.

             The PTHREAD support is still very experimental. Handle with care.
             See also a file README.PTHREAD included in floyd source tree.

     -F      Forks one child process and the parent detaches.  If there is any
             job which should be run as a thread it is fired up by the forked
             child after the the parent is detached.  Unlike the option -D, It
             can be placed on any location of the command line.  For PTHREAD
             supporting version only.

     -l <blink@LA1>
             Blinking interval at load average 1.0 is set to blink@LA1 (msec,
             float expression accepted).  Default interval at load average 1.0
             is 200msec which is calibrated for personal client machines with
             rather light load.  Try increasing blink@LA1 by of 5x, 10x,
             100x... etc.  for a heavily loaded big servers.

     -m <maxblink>
             Maxium blinking interval is set to maxblink (msec, float
             expression accepted).  The default maxblink is about 1000msec.
             You can select larger value to display difference of comparative
             light load (between 0.0 to 0.2).  With the default blink@LA1 of
             200msec, blinking interval reaches the maxblink 1000msec about
             load average 0.2.

     -u <updatecycle>
             The LED blinking interval is updated in response to the current
             load average every four second by default.  This option -u
             changes the the update cycle to updatecycle which should be
             specified in seconds.  A float expression is acceptable, but it
             will be casted into integer after all.  Updatecycle can not be
             tuned to less than 1 second (automatically forced to be the
             minimum).

     -s <sleep>
             By default, A fixed sleep (perhaps 50msec) is inserted after an
             LED on/off cycle in hope of reducing CPU cycle.  This option -s
             sets the sleep to sleep (msec, float expression accepted).

     -b <bigloadsw>
             By default, the LED turn-on period is 100msec in comparative
             light load, and switches to 50msec in heavier load above a
             threshold bigloadsw, which can be specified with this option -b
             in a float format.  This option may be removed in future release.

     -a <1|5|15>
             Select load average over 1, 5, or 15 minutes to be displayed.  By
             default, load average over 1 minute is displayed unless any of
             these options is specified.  For example,

                   $ floyd -v -Na1 -D -Ca5 -D -Sa15 -D
              forks three child processes each displaying load averages over
             1, 5, and 15 minutes by NumLock, CapsLock, and ScrollLock LED.
             Option -a 2, and -a 3 are allowed as aliases for -a 5, and -a 15.

EXAMPLES
     Floyd can be invoked from your console:

           $ floyd &
      If you have an appropriate write permission, you can start floyd for any
     of /dev/tty[0-9]:

           # floyd < /dev/tty0

     even from xterm 1.  Or if you just cannot start floyd from X environment
     (ie. from xterm 1(),) start floyd before invoking X server:

           $ floyd & exec xinit

      or flip to another VC if it's possible, and then start floyd there.

     From a startup file such as rc.local, you can use such a trick as:

           # Start ours anyway,
           floyd -b 9.9 -SD < /dev/tty0
           # then clone LED flags all over the VCs with floyd
           for i in /dev/tty[0-9]
           do floyd $i & sleep 1 ; kill $!
           done

      to control LEDs of all the VCs tty0 to tty9 with just one floyd.  Maybe
     more refined version of this script can be found as rc.floyd in the
     source directory.  This script is tested only in linux 2.0.3[67] and
     2.2.{9,10}, and perhaps it relies on linux kernel feature (or bug maybe).

FILES
     /proc/loadavg   Source of load average value
     rc.floyd        Sample startup script (in the source directory)
     README.PTHREAD  Notes on PTHREAD support (in the source directory)
     BLACKLIST       of the floyd incompatible keyboards

SEE ALSO
     proc(5), setleds(1), kill(1)

DIAGNOSTICS
     If your keyboard seems like being dead but floyd is still pulsuating,
     just try CTRL-Q, for you might have accidentally pressed CTRL-S (in that
     case of deadlock, ScrollLock LED may be illuminating).

     Maybe you can use floyd to check if your kernel is dead or alive if you
     are lucky enough, or maybe you just can't.  Most of `system freeze'
     status are the death of console, in which perhaps (I am not quite sure,
     though) floyd is dead as well.  However, even in that situation, the
     network interface may be still alive (mostly, or likely, I don't know).
     So, even if both the keyboard and floyd are totally dead, don't forget to
     try to login via network before you go over to reset key.

     Some of PC keyboards are proved to be floyd incompatible. Refer to
     BLACKLIST included in the floyd source tree.

     floyd exits with status 0 when killed with a signal SIGINT, SIGTERM, or
     SIGHUP, otherwise with non-zero status (eg. on error, or killed with
     other signals).

BUGS
     Wouldn't stop even when PC battery wears unless explicitly killed.

     Most of PC LEDs are not a red round one.

     Currently runs only on Linux.

     Current floyd cannot detect whether the keyboard is connected or not.  If
     the keyboard is disconnected while floyd is running, the %CPU of floyd
     goes up very high, and it surely damages the computer's performance.  Do
     not run floyd if you don't know if the keyboard is surely connected to
     the machine.

AUTHOUR
     Seiichi Namba <sn@asahi-net.email.ne.jp> © 1999

CONTRIBUTORS
     ZAP03216@nifty.ne.jp (Masanori Kobayasi)
                           Infos on Floyd, bug reports
     CXA01035@nifty.ne.jp (Zophos)
                           Original authour of packetload.c (© 1999 Zophos)

LINUX 2.x                        Jul 25, 1999                        LINUX 2.x