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 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 value is explicitly specified with -s option, the 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 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 (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 by of 5x, 10x, 100x... etc. for a heavily loaded big servers.

-m <maxblink>
    Maxium blinking interval is set to (msec, float expression accepted). The default is about 1000msec. You can select larger value to display difference of comparative light load (between 0.0 to 0.2). With the default of 200msec, blinking interval reaches the 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 which should be specified in seconds. A float expression is acceptable, but it will be casted into integer after all. 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 (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 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 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)