---------------------------------------------------
spinner 1.1 by Joe Laffey, LAFFEY Computer Imaging.
---------------------------------------------------
Doc: $Revision: 1.2 $

Visit http://www.laffeycomputer.com/ for updates.


	This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

-------------
WHAT IS IT?
-------------

Spinner is a small program that displays a little "spinning" ASCII character
in the top left corner of your terminal. To make this effect it cycles
through punctuation marks like this " - \ | / - \ | / ... " (try it to see).
By default the character is drawn in inverse video (or your terminal's
equivalent). But you can turn this off with the -i switch. It supports any
terminal capable of handling VT100 style escape codes.

Spinner is useful for keeping telnet and ssh links from dropping due to
inactivity. Many firewalls, and some ISPs drop connections when they are
perceived as idle. By having spinner running the server is constantly
sending a tiny amount of data over the link, preserving the connection.
Thus (for search engines) Spinner is an anti-dle, timeout preventing,
background daemon process for unix variants including linux. Spinner is
known to compile and work properly under NetBSD 1.5 and 1.6, Mac OS X 10.2,
linux 2.2 and 2.4.

Spinner also has a (mainly fun) mode I like to call "Ghost in the Machine"
mode. In this mode you can use spinner to write the spinner character to
ANY tty, not just your own. This requires adequate permissions, of course.
(see below)


-----------------
HOW DO I USE IT?
-----------------

Basic summary: (spinner -h)

Usage:  spinner[-IutTv[p|P][f|F]] [delay]
        -I   Do *not* use inverse video for spinner
        -u   Delay is in microseconds instead of seconds
        -T   Ignore incompatible TERM environment var setting
        -v   Verbose mode (lots of output)
        -P   Do *not* change process priority (default is to make nice)
        -p   <priority> Specify process priority to use.
        -f   <path> Set pid file path (default is $HOME/.spinner.pid)
        -F   Do *not* create a pid file
        -t   <tty path> Specify path to tty to write to
        -r   Reset term on quit (Use if you get left in inverse a lot.)
        -R   Reset the term and Quit (nothing else)
        -L   Display the license.
Returns: 0 on success, non-zero on failure.
Launches into the background on success.
Use: kill `cat <pidfile>` to stop.
Delays shorter than 1 sec may cause display update issues!


----------------
IMPORTANT INFO   <--read this
----------------

* IN ORDER FOR SPINNER TO PREVENT IDLE CONNECTIONS YOU MUST RUN IT ON THE
SERVER. If you run Spinner on your client the data is not sent over the
wire. It is only drawn locally. So you must run Spinner on the remote
machine to keep the data coming to your terminal over the wire. If you do
not have root access on the remote machine you can still use Spinner.
Compile Spinner with "make". Then just copy the binary executable "spinner"
wherever you'd like. You can then launch Spinner from your .login file if
you wish.

* Spinner is a daemon process (also known as a background process). When
you start spinner it will launch into the background as not to interfere
much with your foreground jobs. By default Spinner creates a pid (process 
id) file called ".spinner.pid" in your home directory. (You may use the -f
or -F switches to modify this behavior.) Note this pid file has a "."
character in front so you will need to use ls -a to see it in a listing.
You can use this file to easily kill Spinner with the command:

   kill `cat ~/.spinner.pid`
   
Note that those are backticks (top left key below ESC, same key with ~).
Of course you can also just find Spinner in your process list and kill
it manually that way. Spinner's pid file is NOT a lock file. It will be
overwritten every time you launch a copy of Spinner. So if you have
multiple spinners running you will have to kill them manually.

Spinner *should* commit suicide (i.e. quit) if the tty to which it is 
writing is no longer active. Sometimes, if you start Spinner writing
to another tty when that tty is not active to begin with Spinner will
not quit. (Anyone know why?? Tell me.)

* Since Spinner draws to the terminal it is possible (and likely) that
the spinner character will end up in the terminal's scrollback. To
reduce this annoyance you can use a long delay. You may also kill
SPinner with the STOP signal (kill -STOP `cat ~/.spinner.pid`) and
then continue it after you get your scrollback via the CONT signal 
(kill -CONT `cat ~/.spinner.pid`).

*Spinner may interfere with the display of mouse selections. If you drag 
out a selection the highlighted text may become unhighlighted as sooner
as Spinner draws to the terminal. Typically the contents of the paste 
buffer still remain, however. So even though you loose the highlighting 
you can still paste the text that you selected in the usual fashion.

* At startup spinner checks to be sure your TERM environemnt variable
is set to "vt100" or "vt102". It only checks for these since these are
the only terminal types that I KNOW will acccept the vt100 escape codes
(to move the cursor, inverse video, etc.) Spinner works perfectly
well in every terminal I have tried it in (including GNU screen, eterm,
xterm, aterm, etc.) If you get the message about your terminal not
being "vt100" or "vt102" simply invoke Spinner with the -T switch. This
forces Spinner to ignore the TERM setting. Note that if you use spinner
on a dumb terminal, or any other terminal that does not support the
escape codes you will see a lot garbage characters. Just stop Spinner
and get a real terminal! If you find this check annoying, or think
it should go away let me know. I may add a config options when Spinner
is moved to the autoconf build system.

* Note that if you would like to use Spinner in conjunction with the GNU
screen program (one of the world's coolest programs, screen is a 
"terminal multiplexer" allowing multiple virtual terminals in a single
terminal window, switching between them, detaching and resumeing screens
both local and remote, etc.) you will want to start Spinner *BEFORE* you
start screen. Otherwise Spinner will end up in one of screen's virtual
terminals, which means that it may not be on the real terminal all the
time. This could lead to an idle timeout, which is exactly what Spinner
was coded to prevent. You may also be able to determine your parent
tty (the original tty from which you invoked screen), and have Spinner 
write to that tty using the -t switch.

* In normal operation (delay >= 2 sec) Spinner functions well with most
terminals / emulators. However, if you switch to microsecond mode for 
the delay (-u) and use lower delays it is possible that your terminal
will become somewhat garbled. You will notice that parts of the screen
that shouldn't be are displayed in inverse text, or text is in the wrong
place, etc. Setting a higher delay will normally make this issue
non-existent. Note that "Terminal.app" under Mac OSX seems more prone to
do this. Gnome term and eterm, etc seem immune.

If you use an extremely low delay on a slow link, or use a slow-drawing
terminal, be prepared for Spinner to slow your terminal down. I would say,
"Don't do that!" Spinner is coded to be very efficient in its main loop.
Only one write statement and one check to be sure the tty is active per
iteration. Since Spinner is meant as an anti-idle tool you will most
likely keep the delay high (but less than 30 sec or so depending upon
what it is that is timing out your connection to begin with).


* By default Spinner will set its process priority (niceness) to 10. You
can use the -p or -P switches to modify this behavior.

* Sometimes when you terminate Spinner it could leave the terminal in a 
state you were not expecting (e.g. inverse video "stuck" on, cursor in
the wrong spot, etc.) If you experience this a lot consider the -r switch.
This will send a vt100 reset code at quit, which usually helps, but will
clear your terminal screen. 

If your terminal gets stuck in an inconsistent (read "whacked") state you
can try to fix it by running Spinner with the -R switch. With this switch
ALL Spinner will do is sen a vt100 reset code to the tty (then quit).

* Verbose mode will walk you through most of the steps Spinner takes as it
launches. Mainly for debugging, it can help you troubleshoot switch
settings, however.

* Ghost in the Machine mode (i.e. using the -t switch to write to another
tty other than your controlling terminal) can be both fun and (a little)
useful. Do use this mode determine the PATH to the tty you want Spinner
to write. Usually the "tty" command will display your own terminal. This
should give you the basic path/filename structure (usually "/dev/ttypXX"
where "XX" is a number). Then do a "who" command to see which particular
tty you want to write to. This will show you a list of logged in users
and their ttys. Next run spinner with the -t switch and specify the path
to the desired tty. Note that you must have permission to write to the
desired tty. Ttys are setup to be owned by the user logged into them, and 
usually setup with a group of "tty". So you can always write to any of 
your own ttys. To write to someone else's tty you either need to be root,
or root needs to setup Spinner as setgid (not setuid) "tty". There are
security concerns with any setuid or setgid program. So don't be
surprised if your administrator says no. Spinner has not been thoroughly
audited for security. Though little could go wrong, small seemingly
meaningless things can lead to real big security holes. You've been 
warned. Spinner is NOT installed setgid (or setuid) by using the 
"make install" command.



-------------
TO DO
-------------
Perhaps Spinner should log results to a file. This may be overkill.

Allowing the user to specify the position of the spinning character
might be fun, and somewhat useful.

Perhaps putting the spinner into a banner at the top or bottom of the
screen (like GNU screen's dividers) would be useful, as they spinner
would not encroach into the active terminal area (the virtual terminal
would be made smaller)

Adding a spinner to the existing banner in the GNU screen program would
be very useful for those who use screen.

Calls to signal() should be replaced with sigaction() stuff.

Any way to prevent scrollback of the spinner character instead of valid
data would be useful (such as the banner at the bottom previously
mentioned).

Perhaps a switch to kill running Spinner(s) instead of using the kill
command might be useful for novie users. However, novice users are
unlikely to be using Spinner to begin with...

---------------------
Who Made This Thing? (and Why?)
---------------------
Joe Laffey <joe@laffeycomputer.com>
I made it to keep alive ssh connections that were being timed out by my
firewalls. Plus it looks cool, and was a nice experiment in writing
directly to ttys.
