This file contains the documentation for the installation and
use of the fanout module.  While a short document, it is still
broken into the following sections:
 - Purpose
 - Installation
 - Bugs and Issues


-PURPOSE
   The fanout device replicates data sent to it out to all
listeners.  This device is a lightweight way to distribute
messages to several processes.

The following example illustrates what fanout does.  At a
bash prompt enter:
  cat /dev/fanout &
  cat /dev/fanout &
  cat /dev/fanout &
  echo "Hello World" >/dev/fanout

Your terminal should display the following:
  Hello World
  Hello World
  Hello World



-INSTALLATION
   The fanout device is implemented as a Linux 2.6 module.  Be
sure to have your running kernel's source code in /usr/src/linux.
Untar the fanout files and make the module:
  cd /usr/src/linux
  tar -xzf fanout.tgz
  cd fanout
  make

When you install the module you can set the size of the circular
buffer and can set the verbosity of the printk messages.  The
default buffer size is 4k and the default debug level is 2.  A
debug level of 3 traces all calls in the module and a debug level
of 0 suppresses all printk messages.  Here is an example that
overwrites the default values for buffer size and debug level:
  insmod ./fanout.ko buf_sz=8192 debuglvl=3

Fanout uses a kernel assigned major number so you need to look
at /proc/devices to see what was assigned.  The following lines
create all ten of the possible instances of a fanout device.
  MAJOR=`grep fanout /proc/devices | awk '{print $1}'`
  mknod /dev/fanout c $MAJOR 0
  mknod /dev/fanout1 c $MAJOR 1
  mknod /dev/fanout2 c $MAJOR 2
  mknod /dev/fanout3 c $MAJOR 3
  mknod /dev/fanout4 c $MAJOR 4
  mknod /dev/fanout5 c $MAJOR 5
  mknod /dev/fanout6 c $MAJOR 6
  mknod /dev/fanout7 c $MAJOR 7
  mknod /dev/fanout8 c $MAJOR 8
  mknod /dev/fanout9 c $MAJOR 9


-BUGS and ISSUES
   This device works well for distribution of events or other
simple messages.  It does *not* handle distribution of large 
files or video streams.  If the circular queue wraps before a
reader can get to the data, the reader is given an EPIPE error.
This means the burden is on the readers to keep up, not on the
writer to slow down.

The module author's indented use of fanout is as a target for
syslog messages.   This explains why the author wants to not
block writing processes at the expense of losing reading
processes once in awhile.