==============
gatherer specs
==============

WORK IN PROGRESS

When a command is expected, the line "#X#" is printed, where X is the number of
the request, starting a 0 and incremented after each processed request.

Requests are spanned on multiple lines. The first line is the command, the
following lines are parameters (one parameter per line unless stated otherwise).

Requests are all blocking. As they are read from stdin using readline(),
they can be buffered in stdin.

When the number of parameters or returns is variable, it should be indicated
first.
When a parameter or returned value is not one line of printable characters,
its length as returned by len() should be indicated first.

When gatherer is expected to write in a file, its parent directory should exist
and it will be opened with the "w" flag (unless stated otherwise).

No timeout handling should be implemented in gatherer.
SIGINT should be handled and:
- stop the current request, write INTERRUPTED to stderr then continue the normal
  flow of execution when a request is being handled,
- be treated as an 'exit' request is a command was being read
- be treated as a 'reset' if a command was already read, but the request is
  still being read. The current request should be dropped and a new request
  should be read, the request counter is not incremented as no request was
  processed.

stderr is used:
- by Python to display exceptions;
- to print "ALIVE" when SIGUSR1 is received or after a "ping" request;
- to print "UNKNOWN COMMAND" when a command is unknown;
- to print "INTERRUPTED" when a command is interrupted with SIGINT.

Requests
--------

Command: "noop"
Params:
- None
Action:
- None
Returns:
- Nothing

Command: "ping"
Params:
- None
Action:
- Prints "ALIVE" on stderr
Returns:
- Nothing

Command: "exit"
Params:
- None
Action:
- The gatherer process returns 0
Returns:
- Nothing

Command: "glob"
Params:
- The globbing pattern
Action:
- Performs a glob.glob()
Returns:
- On the first line, a number of results, n
- On the following n lines, filenames, line by line

Command: "exec"
Params:
- The command to send to a shell
Action:
- Executes the command in a shell using subprocess.Popen
Returns:
- The return code of the command
- The length of its stdout output as return by len(), in decimal.
- Its stdout output, followed by a trailing '\n'
- The length of its stderr output as return by len(), in decimal.
- Its stderr output, followed by a trailing '\n'

Command: "exec2file"
Params:
- The command to send to a shell
- The filename to send the standard output to
Action:
- If the command is found, it is executed with this file as stdout and stderr.
Returns:
- The return code of the command in decimal.

Command: "cp"
-- to be defined after staring at the current sosreport code.

Command: "globcp"
-- to be defined after staring at the current sosreport code.