pipe.c

   File         : pipe.c
   Description  : Bidirectional Pipe to an External Process
   Category     : Utility
   Author       : Charles Yates
  
   The PIPE structure provides a general means to implement a bidirectional
   pipe to a process (the logical equivalent of the invalid popen( command, "r+" ) 
   function call).
  
   Example of use:
  
    char *command = "/path/file";
    char **args = { "arg1", "arg2", "arg3", NULL };
    char **env = { "name=value", NULL };
  
    PIPE p = PIPE_Init( command, args, env );
    if ( PIPE_Run( p ) == 0 )
    {
        FILE *reader = PIPE_GetReader( p );
        FILE *writer = PIPE_GetWriter( p );
        ... do io on reader and writer ...
    }
    PIPE_Close( p );
  
   Notes:
  
   1)   Either args or env can be NULL.
   2)   Neither reader nor writer should be closed by the caller.
   3)   It is assumed that the command itself will terminate when either its
        stdin or stdout is closed.

   PIPE PIPE_Init( char *command, char **args, char **env )
 
   Function     : PIPE_Init
   Description  : Initialises a pipe structure
   Input        : char *command - command to execute
                  char **args - NULL terminated array of args
                  char **env - NULL terminated array of environment vars
   Output       : void
   Returns      : An initialised pipe structure

   int PIPE_Run( PIPE p )
 
   Function     : PIPE_Run
   Description  : Executes the pipe command
   Input        : PIPE pipe - pipe to use
   Output       : command is executed and Reader/Writer initialised
   Returns      : int - 0 when successful

   FILE *PIPE_GetWriter( PIPE p )
 
   Function     : PIPE_GetWriter
   Description  : Returns the file pointer to the pipes input
   Input        : PIPE pipe - pipe to use
   Output       : void
   Returns      : FILE * of writer

   FILE *PIPE_GetReader( PIPE p )
 
   Function     : PIPE_GetReader
   Description  : Returns the file pointer to the pipes output
   Input        : PIPE pipe - pipe to use
   Output       : void
   Returns      : FILE * of reader

   void PIPE_Close( PIPE p )
 
   Function     : PIPE_Close
   Description  : Closes the pipe
   Input        : PIPE pipe - pipe to use
   Output       : pipe is closed
   Returns      : void

   void PIPE_Kill( PIPE p )
 
   Function     : PIPE_Kill
   Description  : Closes and kills the pipe
   Input        : PIPE pipe - pipe to use
   Output       : pipe is closed
   Returns      : void