Logger module - README

------------------------------------- Goal--------------------------------------

   Module logs incoming UniRec records into stdout or into specified file(s).

----------------------------------- Method -------------------------------------

   Module specific parameters:
        UNIREC_FMT  The i-th parameter of this type specifies format of UniRec
                    expected on the i-th input interface.
   -w   FILE        Write output to FILE instead of stdout (rewrite the file).
   -a   FILE        Write output to FILE instead of stdout (append to the end).
   -o   OUT_FMT     Set of fields included in the output (UniRec specifier).
                    Union of all input formats is used by default.
   -t               Write names of fields on the first line.
   -T               Add the time when the record was received as the first field.
   -n               Add the number of interface the record was received on as the
                    first field (or second when -T is specified).
   -c   N           Quit after N records are received.
   -d   X           Optionally modifies delimiter to inserted value X
                    (implicitely ','). Delimiter has to be one character long,
                    except for printable escape sequences.

  Common TRAP parameters:
   -h               Print this message.
   -i   IFC_SPEC    Specification of interface types and their parameters.
   -v               Be verbose.
   -vv              Be more verbose.
   -vvv             Be even more verbose.

   Format of IFC_SPEC:
   <ifc_types>;<params1>;<params2>;...;<paramsN>
   -   N is number of module's interfaces (both input and output).
   -   <ifc_types> is a string of length N where i-th character specifies a type
       of the i-th interface (input interfaces first, then output interfaces).
   -   <paramsI> specifies parameters for I-th interface. Format is specific for
       each interface type.

---------------------------------- Algorithm -----------------------------------

   -  Each record is written as one line containing values of its fields in
      human-readable format separated by chosen delimiters (CSV format).
   -  Number of input intefaces and their UniRec formats are given on command
      line (if you specify N UniRec formats, N input interfaces will be created).
   -  Output contains union of all fields of all input formats by default, but
      it may be redefined using -o option.

---------------------------------- Interfaces ----------------------------------

   Input interface: variable
   Output interface: 0

Interface types available:
  Shared Memory interface ('m')
    Communicates though a shared memory (shm_open...).
    Parameters when used as INPUT interface:
      <identifier>
      identifier - string used for sender's memory identification,
        consisting of alphanumerical characters: "[a-zA-Z0-9]+"
    Parameters when used as OUTPUT interface:
      <identifier>
      identifier - string used for memory unique identification,
        consisting of alphanumerical characters: "[a-zA-Z0-9]+"
  TCP interface ('t')
    Communicates through a TCP socket. Output interface listens on a given port,
    input interface connects to it. There may be more than one input interfaces
    connected to one output interface, every input interface will get the same data.
    Parameters when used as INPUT interface:
      <hostname or ip>,<port>
      Hostname/IP and port to connect to must be specified.
    Parameters when used as OUTPUT interface:
      <port>,<max_num_of_clients>
      Port to listen on and maximal number of clients (input interfaces) allowed
      must be specified.
  TCP interface - UNIX socket ('u')
    Communicates through a UNIX socket. Output interface listens on a given port,
    input interface connects to it. There may be more than one input interfaces
    connected to one output interface, every input interface will get the same data.
    Parameters are the same as for TCP interface ('t').
  Blackhole interface ('b')
    Can be used as OUTPUT interface only. Does nothing, everything which is sent
    by this interface is dropped. It has no parameters.

Example usage for a module with one input interface and two output interfaces:
  ./my_module -i "tbt;localhost,12345;;23456,5"
  The input interface will connect to localhost:12345. The first output
  interface is unused (all data send there will be dropped), the second output
  interface will provide data on port 23456, to which another module can connect
  its input interface.

Note: Don't forget to enclose IFC_SPEC in quotation marks, otherwise a shell
will treat semicolons as command separators.

--------------------------------------------------------------------------------
