CMake/Source/kwsys/Process.h.in

/*=========================================================================

  Program:   KWSys - Kitware System Library
  Module:    $RCSfile$
  Language:  C++
  Date:      $Date$
  Version:   $Revision$

  Copyright (c) 2002 Kitware, Inc., Insight Consortium.  All rights reserved.
  See http://www.cmake.org/HTML/Copyright.html for details.

     This software is distributed WITHOUT ANY WARRANTY; without even
     the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
     PURPOSE.  See the above copyright notices for more information.

=========================================================================*/
#ifndef @KWSYS_NAMESPACE@_Process_h
#define @KWSYS_NAMESPACE@_Process_h

#include <@KWSYS_NAMESPACE@/Configure.h>

/* Redefine all public interface symbol names to be in the proper
   namespace.  These macros are used internally to kwsys only, and are
   not visible to user code.  Use kwsysHeaderDump.pl to reproduce
   these macros after making changes to the interface.  */
#define kwsys(x) @KWSYS_NAMESPACE@##x
#define kwsysEXPORT                      @KWSYS_NAMESPACE@_EXPORT
#define kwsysProcess                     kwsys(Process)
#define kwsysProcess_s                   kwsys(Process_s)
#define kwsysProcess_New                 kwsys(Process_New)
#define kwsysProcess_Delete              kwsys(Process_Delete)
#define kwsysProcess_SetCommand          kwsys(Process_SetCommand)
#define kwsysProcess_AddCommand          kwsys(Process_AddCommand)
#define kwsysProcess_SetTimeout          kwsys(Process_SetTimeout)
#define kwsysProcess_SetWorkingDirectory kwsys(Process_SetWorkingDirectory)
#define kwsysProcess_Option_HideWindow   kwsys(Process_Option_HideWindow)
#define kwsysProcess_GetOption           kwsys(Process_GetOption)
#define kwsysProcess_SetOption           kwsys(Process_SetOption)
#define kwsysProcess_Option_e            kwsys(Process_Option_e)
#define kwsysProcess_State_Starting      kwsys(Process_State_Starting)
#define kwsysProcess_State_Error         kwsys(Process_State_Error)
#define kwsysProcess_State_Exception     kwsys(Process_State_Exception)
#define kwsysProcess_State_Executing     kwsys(Process_State_Executing)
#define kwsysProcess_State_Exited        kwsys(Process_State_Exited)
#define kwsysProcess_State_Expired       kwsys(Process_State_Expired)
#define kwsysProcess_State_Killed        kwsys(Process_State_Killed)
#define kwsysProcess_GetState            kwsys(Process_GetState)
#define kwsysProcess_State_e             kwsys(Process_State_e)
#define kwsysProcess_Exception_None      kwsys(Process_Exception_None)
#define kwsysProcess_Exception_Fault     kwsys(Process_Exception_Fault)
#define kwsysProcess_Exception_Illegal   kwsys(Process_Exception_Illegal)
#define kwsysProcess_Exception_Interrupt kwsys(Process_Exception_Interrupt)
#define kwsysProcess_Exception_Numerical kwsys(Process_Exception_Numerical)
#define kwsysProcess_Exception_Other     kwsys(Process_Exception_Other)
#define kwsysProcess_GetExitException    kwsys(Process_GetExitException)
#define kwsysProcess_Exception_e         kwsys(Process_Exception_e)
#define kwsysProcess_GetExitCode         kwsys(Process_GetExitCode)
#define kwsysProcess_GetExitValue        kwsys(Process_GetExitValue)
#define kwsysProcess_GetErrorString      kwsys(Process_GetErrorString)
#define kwsysProcess_Execute             kwsys(Process_Execute)
#define kwsysProcess_WaitForData         kwsys(Process_WaitForData)
#define kwsysProcess_Pipes_e             kwsys(Process_Pipes_e)
#define kwsysProcess_Pipe_STDOUT         kwsys(Process_Pipe_STDOUT)
#define kwsysProcess_Pipe_STDERR         kwsys(Process_Pipe_STDERR)
#define kwsysProcess_Pipe_Timeout        kwsys(Process_Pipe_Timeout)
#define kwsysProcess_WaitForExit         kwsys(Process_WaitForExit)
#define kwsysProcess_Kill                kwsys(Process_Kill)

#if defined(__cplusplus)
extern "C"
{
#endif

/**
 * Process control data structure.
 */
typedef struct kwsysProcess_s kwsysProcess;

/**
 * Create a new Process instance.
 */
kwsysEXPORT kwsysProcess* kwsysProcess_New();

/**
 * Delete an existing Process instance.  If the instance is currently
 * executing a process, this blocks until the process terminates.
 */
kwsysEXPORT void kwsysProcess_Delete(kwsysProcess* cp);

/**
 * Set the command line to be executed.  Argument is an array of
 * pointers to the command and each argument.  Ths array must end with
 * a NULL pointer.  Any previous command lines are removed.  Returns
 * 1 for success and 0 otherwise.
 */
kwsysEXPORT int kwsysProcess_SetCommand(kwsysProcess* cp,
                                        char const* const* command);

/**
 * Add a command line to be executed.  Argument is an array of
 * pointers to the command and each argument.  Ths array must end with
 * a NULL pointer.  If this is not the first command added, its
 * standard input will be connected to the standard output of the
 * previous command.  Returns 1 for success and 0 otherwise.
 */
kwsysEXPORT int kwsysProcess_AddCommand(kwsysProcess* cp,
                                        char const* const* command);

/**
 * Set the timeout for the child process.  The timeout period begins
 * when the child is executed.  If the child has not terminated when
 * the timeout expires, it will be killed.  A non-positive (<= 0)
 * value will disable the timeout.
 */
kwsysEXPORT void kwsysProcess_SetTimeout(kwsysProcess* cp, double timeout);

/**
 * Set the working directory for the child process.  The working
 * directory can be absolute or relative to the current directory.
 */
kwsysEXPORT void kwsysProcess_SetWorkingDirectory(kwsysProcess* cp,
                                                  const char* dir);

/**
 * Get/Set a platform-specific option.  Possible options are:
 *
 *  kwsysProcess_Option_HideWindow = Whether to hide window on Windows.
 *         0 = No (default)
 *         1 = Yes
 */
kwsysEXPORT int kwsysProcess_GetOption(kwsysProcess* cp, int optionId);
kwsysEXPORT void kwsysProcess_SetOption(kwsysProcess* cp, int optionId,
                                        int value);
enum kwsysProcess_Option_e
{
  kwsysProcess_Option_HideWindow
};

/**
 * Get the current state of the Process instance.  Possible states are:
 *
 *  kwsysProcess_State_Starting  = Execute has not yet been called.
 *  kwsysProcess_State_Error     = Error administrating the child process.
 *  kwsysProcess_State_Exception = Child process exited abnormally.
 *  kwsysProcess_State_Executing = Child process is currently running.
 *  kwsysProcess_State_Exited    = Child process exited normally.
 *  kwsysProcess_State_Expired   = Child process's timeout expired.
 *  kwsysProcess_State_Killed    = Child process terminated by Kill method.
 */
kwsysEXPORT int kwsysProcess_GetState(kwsysProcess* cp);
enum kwsysProcess_State_e
{
  kwsysProcess_State_Starting,
  kwsysProcess_State_Error,
  kwsysProcess_State_Exception,
  kwsysProcess_State_Executing,
  kwsysProcess_State_Exited,
  kwsysProcess_State_Expired,
  kwsysProcess_State_Killed
};

/**
 * When GetState returns "Exception", this method returns a
 * platform-independent description of the exceptional behavior that
 * caused the child to terminate abnormally.  Possible exceptions are:
 *
 *  kwsysProcess_Exception_None      = No exceptional behavior occurred.
 *  kwsysProcess_Exception_Fault     = Child crashed with a memory fault.
 *  kwsysProcess_Exception_Illegal   = Child crashed with an illegal instruction.
 *  kwsysProcess_Exception_Interrupt = Child was interrupted by user (Cntl-C/Break).
 *  kwsysProcess_Exception_Numerical = Child crashed with a numerical exception.
 *  kwsysProcess_Exception_Other     = Child terminated for another reason.
 */
kwsysEXPORT int kwsysProcess_GetExitException(kwsysProcess* cp);
enum kwsysProcess_Exception_e
{
  kwsysProcess_Exception_None,
  kwsysProcess_Exception_Fault,
  kwsysProcess_Exception_Illegal,
  kwsysProcess_Exception_Interrupt,
  kwsysProcess_Exception_Numerical,
  kwsysProcess_Exception_Other
};

/**
 * When GetState returns "Exited" or "Exception", this method returns
 * the platform-specific raw exit code of the process.  UNIX platforms
 * should use WIFEXITED/WEXITSTATUS and WIFSIGNALED/WTERMSIG to access
 * this value.  Windows users should compare the value to the various
 * EXCEPTION_* values.
 *
 * If GetState returns "Exited", use GetExitValue to get the
 * platform-independent child return value.
 */
kwsysEXPORT int kwsysProcess_GetExitCode(kwsysProcess* cp);

/**
 * When GetState returns "Exited", this method returns the child's
 * platform-independent exit code (such as the value returned by the
 * child's main).
 */
kwsysEXPORT int kwsysProcess_GetExitValue(kwsysProcess* cp);

/**
 * When GetState returns "Error", this method returns a string
 * describing the problem.  Otherwise, it returns NULL.
 */
kwsysEXPORT const char* kwsysProcess_GetErrorString(kwsysProcess* cp);

/**
 * Start executing the child process.
 */
kwsysEXPORT void kwsysProcess_Execute(kwsysProcess* cp);

/**
 * Block until data are available on a requested pipe, a timeout
 * expires, or the child process terminates.  Arguments are as
 * follows:
 *
 *  pipes   = Flags for the child output pipes of interest to the caller.
 *            Possible values are Pipe_STDOUT and Pipe_STDERR.  Multiple
 *            pipes may be specified by using the bitwise OR operator '|'.
 *  data    = If data are read, the pointer to which this points is
 *            set to point to the data.
 *  length  = If data are read, the integer to which this points is
 *            set to the length of the data read.
 *  timeout = Specifies the maximum time this call may block.  Upon
 *            return after reading data, the time elapsed is subtracted
 *            from the timeout value.  If this timeout expires, the
 *            value is set to 0.  A NULL pointer passed for this argument
 *            indicates no timeout for the call.
 *
 * Return value will be one of:
 *
 *   0            = No more data will be available from the child process,
 *                  or no process has been executed.  WaitForExit should
 *                  be called to wait for the process to terminate.
 *   Pipe_STDOUT  = Data have been read from the child's stdout pipe.
 *   Pipe_STDERR  = Data have been read from the child's stderr pipe.
 *   Pipe_Timeout = No data available within timeout specified for the
 *                  call.  Time elapsed has been subtracted from timeout
 *                  argument.
 */
kwsysEXPORT int kwsysProcess_WaitForData(kwsysProcess* cp, int pipes,
                                         char** data, int* length,
                                         double* timeout);
enum kwsysProcess_Pipes_e
{
  kwsysProcess_Pipe_STDOUT=1,
  kwsysProcess_Pipe_STDERR=2,
  kwsysProcess_Pipe_Timeout=255
};

/**
 * Block until the child process terminates or the given timeout
 * expires.  If no process is running, returns immediatly.  The
 * argument is:
 *
 *  timeout = Specifies the maximum time this call may block.  Upon
 *            returning due to child termination, the elapsed time
 *            is subtracted from the given value.  A NULL pointer
 *            passed for this argument indicates no timeout for the
 *            call.
 *
 * Return value will be one of:
 *
 *    0 = Child did not terminate within timeout specified for
 *        the call.  Time elapsed has been subtracted from timeout
 *        argument.
 *    1 = Child has terminated or was not running.
 */
kwsysEXPORT int kwsysProcess_WaitForExit(kwsysProcess* cp, double* timeout);

/**
 * Forcefully terminate the child process that is currently running.
 * The caller should call WaitForExit after this returns to wait for
 * the child to terminate.
 */
kwsysEXPORT void kwsysProcess_Kill(kwsysProcess* cp);

#if defined(__cplusplus)
} /* extern "C" */
#endif

/* If we are building a kwsysProcess .c file, let it use these macros.
   Otherwise, undefine them to keep the namespace clean.  */
#if !defined(KWSYS_IN_PROCESS_C)
# undef kwsys
# undef kwsysEXPORT
# undef kwsysProcess
# undef kwsysProcess_s
# undef kwsysProcess_New
# undef kwsysProcess_Delete
# undef kwsysProcess_SetCommand
# undef kwsysProcess_AddCommand
# undef kwsysProcess_SetTimeout
# undef kwsysProcess_SetWorkingDirectory
# undef kwsysProcess_Option_HideWindow
# undef kwsysProcess_GetOption
# undef kwsysProcess_SetOption
# undef kwsysProcess_Option_e
# undef kwsysProcess_State_Starting
# undef kwsysProcess_State_Error
# undef kwsysProcess_State_Exception
# undef kwsysProcess_State_Executing
# undef kwsysProcess_State_Exited
# undef kwsysProcess_State_Expired
# undef kwsysProcess_State_Killed
# undef kwsysProcess_GetState
# undef kwsysProcess_State_e
# undef kwsysProcess_Exception_None
# undef kwsysProcess_Exception_Fault
# undef kwsysProcess_Exception_Illegal
# undef kwsysProcess_Exception_Interrupt
# undef kwsysProcess_Exception_Numerical
# undef kwsysProcess_Exception_Other
# undef kwsysProcess_GetExitException
# undef kwsysProcess_Exception_e
# undef kwsysProcess_GetExitCode
# undef kwsysProcess_GetExitValue
# undef kwsysProcess_GetErrorString
# undef kwsysProcess_Execute
# undef kwsysProcess_WaitForData
# undef kwsysProcess_Pipes_e
# undef kwsysProcess_Pipe_STDOUT
# undef kwsysProcess_Pipe_STDERR
# undef kwsysProcess_Pipe_Timeout
# undef kwsysProcess_WaitForExit
# undef kwsysProcess_Kill
#endif

#endif