Source/kwsys/Process.h.in

   1 /*=========================================================================
   2
   3   Program:   KWSys - Kitware System Library
   4   Module:    $RCSfile: Process.h.in,v $
   5
   6   Copyright (c) Kitware, Inc., Insight Consortium.  All rights reserved.
   7   See Copyright.txt or http://www.kitware.com/Copyright.htm for details.
   8
   9      This software is distributed WITHOUT ANY WARRANTY; without even
  10      the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  11      PURPOSE.  See the above copyright notices for more information.
  12
  13 =========================================================================*/
  14 #ifndef @KWSYS_NAMESPACE@_Process_h
  15 #define @KWSYS_NAMESPACE@_Process_h
  16
  17 #include <@KWSYS_NAMESPACE@/Configure.h>
  18
  19 /* Redefine all public interface symbol names to be in the proper
  20    namespace.  These macros are used internally to kwsys only, and are
  21    not visible to user code.  Use kwsysHeaderDump.pl to reproduce
  22    these macros after making changes to the interface.  */
  23 #if !defined(KWSYS_NAMESPACE)
  24 # define kwsys_ns(x) @KWSYS_NAMESPACE@##x
  25 # define kwsysEXPORT @KWSYS_NAMESPACE@_EXPORT
  26 #endif
  27 #define kwsysProcess                     kwsys_ns(Process)
  28 #define kwsysProcess_s                   kwsys_ns(Process_s)
  29 #define kwsysProcess_New                 kwsys_ns(Process_New)
  30 #define kwsysProcess_Delete              kwsys_ns(Process_Delete)
  31 #define kwsysProcess_SetCommand          kwsys_ns(Process_SetCommand)
  32 #define kwsysProcess_AddCommand          kwsys_ns(Process_AddCommand)
  33 #define kwsysProcess_SetTimeout          kwsys_ns(Process_SetTimeout)
  34 #define kwsysProcess_SetWorkingDirectory kwsys_ns(Process_SetWorkingDirectory)
  35 #define kwsysProcess_SetPipeFile         kwsys_ns(Process_SetPipeFile)
  36 #define kwsysProcess_SetPipeNative       kwsys_ns(Process_SetPipeNative)
  37 #define kwsysProcess_SetPipeShared       kwsys_ns(Process_SetPipeShared)
  38 #define kwsysProcess_Option_Detach       kwsys_ns(Process_Option_Detach)
  39 #define kwsysProcess_Option_HideWindow   kwsys_ns(Process_Option_HideWindow)
  40 #define kwsysProcess_Option_Verbatim     kwsys_ns(Process_Option_Verbatim)
  41 #define kwsysProcess_GetOption           kwsys_ns(Process_GetOption)
  42 #define kwsysProcess_SetOption           kwsys_ns(Process_SetOption)
  43 #define kwsysProcess_Option_e            kwsys_ns(Process_Option_e)
  44 #define kwsysProcess_State_Starting      kwsys_ns(Process_State_Starting)
  45 #define kwsysProcess_State_Error         kwsys_ns(Process_State_Error)
  46 #define kwsysProcess_State_Exception     kwsys_ns(Process_State_Exception)
  47 #define kwsysProcess_State_Executing     kwsys_ns(Process_State_Executing)
  48 #define kwsysProcess_State_Exited        kwsys_ns(Process_State_Exited)
  49 #define kwsysProcess_State_Expired       kwsys_ns(Process_State_Expired)
  50 #define kwsysProcess_State_Killed        kwsys_ns(Process_State_Killed)
  51 #define kwsysProcess_State_Disowned      kwsys_ns(Process_State_Disowned)
  52 #define kwsysProcess_GetState            kwsys_ns(Process_GetState)
  53 #define kwsysProcess_State_e             kwsys_ns(Process_State_e)
  54 #define kwsysProcess_Exception_None      kwsys_ns(Process_Exception_None)
  55 #define kwsysProcess_Exception_Fault     kwsys_ns(Process_Exception_Fault)
  56 #define kwsysProcess_Exception_Illegal   kwsys_ns(Process_Exception_Illegal)
  57 #define kwsysProcess_Exception_Interrupt kwsys_ns(Process_Exception_Interrupt)
  58 #define kwsysProcess_Exception_Numerical kwsys_ns(Process_Exception_Numerical)
  59 #define kwsysProcess_Exception_Other     kwsys_ns(Process_Exception_Other)
  60 #define kwsysProcess_GetExitException    kwsys_ns(Process_GetExitException)
  61 #define kwsysProcess_Exception_e         kwsys_ns(Process_Exception_e)
  62 #define kwsysProcess_GetExitCode         kwsys_ns(Process_GetExitCode)
  63 #define kwsysProcess_GetExitValue        kwsys_ns(Process_GetExitValue)
  64 #define kwsysProcess_GetErrorString      kwsys_ns(Process_GetErrorString)
  65 #define kwsysProcess_GetExceptionString  kwsys_ns(Process_GetExceptionString)
  66 #define kwsysProcess_Execute             kwsys_ns(Process_Execute)
  67 #define kwsysProcess_Disown              kwsys_ns(Process_Disown)
  68 #define kwsysProcess_WaitForData         kwsys_ns(Process_WaitForData)
  69 #define kwsysProcess_Pipes_e             kwsys_ns(Process_Pipes_e)
  70 #define kwsysProcess_Pipe_None           kwsys_ns(Process_Pipe_None)
  71 #define kwsysProcess_Pipe_STDIN          kwsys_ns(Process_Pipe_STDIN)
  72 #define kwsysProcess_Pipe_STDOUT         kwsys_ns(Process_Pipe_STDOUT)
  73 #define kwsysProcess_Pipe_STDERR         kwsys_ns(Process_Pipe_STDERR)
  74 #define kwsysProcess_Pipe_Timeout        kwsys_ns(Process_Pipe_Timeout)
  75 #define kwsysProcess_Pipe_Handle         kwsys_ns(Process_Pipe_Handle)
  76 #define kwsysProcess_WaitForExit         kwsys_ns(Process_WaitForExit)
  77 #define kwsysProcess_Kill                kwsys_ns(Process_Kill)
  78
  79 #if defined(__cplusplus)
  80 extern "C"
  81 {
  82 #endif
  83
  84 /**
  85  * Process control data structure.
  86  */
  87 typedef struct kwsysProcess_s kwsysProcess;
  88
  89 /* Platform-specific pipe handle type.  */
  90 #if defined(_WIN32) && !defined(__CYGWIN__)
  91 typedef void* kwsysProcess_Pipe_Handle;
  92 #else
  93 typedef int kwsysProcess_Pipe_Handle;
  94 #endif
  95
  96 /**
  97  * Create a new Process instance.
  98  */
  99 kwsysEXPORT kwsysProcess* kwsysProcess_New(void);
 100
 101 /**
 102  * Delete an existing Process instance.  If the instance is currently
 103  * executing a process, this blocks until the process terminates.
 104  */
 105 kwsysEXPORT void kwsysProcess_Delete(kwsysProcess* cp);
 106
 107 /**
 108  * Set the command line to be executed.  Argument is an array of
 109  * pointers to the command and each argument.  The array must end with
 110  * a NULL pointer.  Any previous command lines are removed.  Returns
 111  * 1 for success and 0 otherwise.
 112  */
 113 kwsysEXPORT int kwsysProcess_SetCommand(kwsysProcess* cp,
 114                                         char const* const* command);
 115
 116 /**
 117  * Add a command line to be executed.  Argument is an array of
 118  * pointers to the command and each argument.  The array must end with
 119  * a NULL pointer.  If this is not the first command added, its
 120  * standard input will be connected to the standard output of the
 121  * previous command.  Returns 1 for success and 0 otherwise.
 122  */
 123 kwsysEXPORT int kwsysProcess_AddCommand(kwsysProcess* cp,
 124                                         char const* const* command);
 125
 126 /**
 127  * Set the timeout in seconds for the child process.  The timeout
 128  * period begins when the child is executed.  If the child has not
 129  * terminated when the timeout expires, it will be killed.  A
 130  * non-positive (<= 0) value will disable the timeout.
 131  */
 132 kwsysEXPORT void kwsysProcess_SetTimeout(kwsysProcess* cp, double timeout);
 133
 134 /**
 135  * Set the working directory for the child process.  The working
 136  * directory can be absolute or relative to the current directory.
 137  * Returns 1 for success and 0 for failure.
 138  */
 139 kwsysEXPORT int kwsysProcess_SetWorkingDirectory(kwsysProcess* cp,
 140                                                  const char* dir);
 141
 142 /**
 143  * Set the name of a file to be attached to the given pipe.  Returns 1
 144  * for success and 0 for failure.
 145  */
 146 kwsysEXPORT int kwsysProcess_SetPipeFile(kwsysProcess* cp, int pipe,
 147                                          const char* file);
 148
 149 /**
 150  * Set whether the given pipe in the child is shared with the parent
 151  * process.  The default is no for Pipe_STDOUT and Pipe_STDERR and yes
 152  * for Pipe_STDIN.
 153  */
 154 kwsysEXPORT void kwsysProcess_SetPipeShared(kwsysProcess* cp, int pipe,
 155                                             int shared);
 156
 157 /**
 158  * Specify a platform-specific native pipe for use as one of the child
 159  * interface pipes.  The native pipe is specified by an array of two
 160  * descriptors or handles.  The first entry in the array (index 0)
 161  * should be the read end of the pipe.  The second entry in the array
 162  * (index 1) should be the write end of the pipe.  If a null pointer
 163  * is given the option will be disabled.
 164  *
 165  * For Pipe_STDIN the native pipe is connected to the first child in
 166  * the pipeline as its stdin.  After the children are created the
 167  * write end of the pipe will be closed in the child process and the
 168  * read end will be closed in the parent process.
 169  *
 170  * For Pipe_STDOUT and Pipe_STDERR the pipe is connected to the last
 171  * child as its stdout or stderr.  After the children are created the
 172  * write end of the pipe will be closed in the parent process and the
 173  * read end will be closed in the child process.
 174  */
 175 kwsysEXPORT void kwsysProcess_SetPipeNative(kwsysProcess* cp, int pipe,
 176                                             kwsysProcess_Pipe_Handle p[2]);
 177
 178 /**
 179  * Get/Set a possibly platform-specific option.  Possible options are:
 180  *
 181  *  kwsysProcess_Option_Detach = Whether to detach the process.
 182  *         0 = No (default)
 183  *         1 = Yes
 184  *
 185  *  kwsysProcess_Option_HideWindow = Whether to hide window on Windows.
 186  *         0 = No (default)
 187  *         1 = Yes
 188  *
 189  *  kwsysProcess_Option_Verbatim = Whether SetCommand and AddCommand
 190  *                                 should treat the first argument
 191  *                                 as a verbatim command line
 192  *                                 and ignore the rest of the arguments.
 193  *         0 = No (default)
 194  *         1 = Yes
 195  */
 196 kwsysEXPORT int kwsysProcess_GetOption(kwsysProcess* cp, int optionId);
 197 kwsysEXPORT void kwsysProcess_SetOption(kwsysProcess* cp, int optionId,
 198                                         int value);
 199 enum kwsysProcess_Option_e
 200 {
 201   kwsysProcess_Option_HideWindow,
 202   kwsysProcess_Option_Detach,
 203   kwsysProcess_Option_Verbatim
 204 };
 205
 206 /**
 207  * Get the current state of the Process instance.  Possible states are:
 208  *
 209  *  kwsysProcess_State_Starting  = Execute has not yet been called.
 210  *  kwsysProcess_State_Error     = Error administrating the child process.
 211  *  kwsysProcess_State_Exception = Child process exited abnormally.
 212  *  kwsysProcess_State_Executing = Child process is currently running.
 213  *  kwsysProcess_State_Exited    = Child process exited normally.
 214  *  kwsysProcess_State_Expired   = Child process's timeout expired.
 215  *  kwsysProcess_State_Killed    = Child process terminated by Kill method.
 216  *  kwsysProcess_State_Disowned  = Child is no longer managed by this object.
 217  */
 218 kwsysEXPORT int kwsysProcess_GetState(kwsysProcess* cp);
 219 enum kwsysProcess_State_e
 220 {
 221   kwsysProcess_State_Starting,
 222   kwsysProcess_State_Error,
 223   kwsysProcess_State_Exception,
 224   kwsysProcess_State_Executing,
 225   kwsysProcess_State_Exited,
 226   kwsysProcess_State_Expired,
 227   kwsysProcess_State_Killed,
 228   kwsysProcess_State_Disowned
 229 };
 230
 231 /**
 232  * When GetState returns "Exception", this method returns a
 233  * platform-independent description of the exceptional behavior that
 234  * caused the child to terminate abnormally.  Possible exceptions are:
 235  *
 236  *  kwsysProcess_Exception_None      = No exceptional behavior occurred.
 237  *  kwsysProcess_Exception_Fault     = Child crashed with a memory fault.
 238  *  kwsysProcess_Exception_Illegal   = Child crashed with an illegal instruction.
 239  *  kwsysProcess_Exception_Interrupt = Child was interrupted by user (Cntl-C/Break).
 240  *  kwsysProcess_Exception_Numerical = Child crashed with a numerical exception.
 241  *  kwsysProcess_Exception_Other     = Child terminated for another reason.
 242  */
 243 kwsysEXPORT int kwsysProcess_GetExitException(kwsysProcess* cp);
 244 enum kwsysProcess_Exception_e
 245 {
 246   kwsysProcess_Exception_None,
 247   kwsysProcess_Exception_Fault,
 248   kwsysProcess_Exception_Illegal,
 249   kwsysProcess_Exception_Interrupt,
 250   kwsysProcess_Exception_Numerical,
 251   kwsysProcess_Exception_Other
 252 };
 253
 254 /**
 255  * When GetState returns "Exited" or "Exception", this method returns
 256  * the platform-specific raw exit code of the process.  UNIX platforms
 257  * should use WIFEXITED/WEXITSTATUS and WIFSIGNALED/WTERMSIG to access
 258  * this value.  Windows users should compare the value to the various
 259  * EXCEPTION_* values.
 260  *
 261  * If GetState returns "Exited", use GetExitValue to get the
 262  * platform-independent child return value.
 263  */
 264 kwsysEXPORT int kwsysProcess_GetExitCode(kwsysProcess* cp);
 265
 266 /**
 267  * When GetState returns "Exited", this method returns the child's
 268  * platform-independent exit code (such as the value returned by the
 269  * child's main).
 270  */
 271 kwsysEXPORT int kwsysProcess_GetExitValue(kwsysProcess* cp);
 272
 273 /**
 274  * When GetState returns "Error", this method returns a string
 275  * describing the problem.  Otherwise, it returns NULL.
 276  */
 277 kwsysEXPORT const char* kwsysProcess_GetErrorString(kwsysProcess* cp);
 278
 279 /**
 280  * When GetState returns "Exception", this method returns a string
 281  * describing the problem.  Otherwise, it returns NULL.
 282  */
 283 kwsysEXPORT const char* kwsysProcess_GetExceptionString(kwsysProcess* cp);
 284
 285 /**
 286  * Start executing the child process.
 287  */
 288 kwsysEXPORT void kwsysProcess_Execute(kwsysProcess* cp);
 289
 290 /**
 291  * Stop management of a detached child process.  This closes any pipes
 292  * being read.  If the child was not created with the
 293  * kwsysProcess_Option_Detach option, this method does nothing.  This
 294  * is because disowning a non-detached process will cause the child
 295  * exit signal to be left unhandled until this process exits.
 296  */
 297 kwsysEXPORT void kwsysProcess_Disown(kwsysProcess* cp);
 298
 299 /**
 300  * Block until data are available on a pipe, a timeout expires, or the
 301  * child process terminates.  Arguments are as follows:
 302  *
 303  *  data    = If data are read, the pointer to which this points is
 304  *            set to point to the data.
 305  *  length  = If data are read, the integer to which this points is
 306  *            set to the length of the data read.
 307  *  timeout = Specifies the maximum time this call may block.  Upon
 308  *            return after reading data, the time elapsed is subtracted
 309  *            from the timeout value.  If this timeout expires, the
 310  *            value is set to 0.  A NULL pointer passed for this argument
 311  *            indicates no timeout for the call.  A negative or zero
 312  *            value passed for this argument may be used for polling
 313  *            and will always return immediately.
 314  *
 315  * Return value will be one of:
 316  *
 317  *   Pipe_None    = No more data will be available from the child process,
 318  *    ( == 0)       or no process has been executed.  WaitForExit should
 319  *                  be called to wait for the process to terminate.
 320  *   Pipe_STDOUT  = Data have been read from the child's stdout pipe.
 321  *   Pipe_STDERR  = Data have been read from the child's stderr pipe.
 322  *   Pipe_Timeout = No data available within timeout specified for the
 323  *                  call.  Time elapsed has been subtracted from timeout
 324  *                  argument.
 325  */
 326 kwsysEXPORT int kwsysProcess_WaitForData(kwsysProcess* cp, char** data,
 327                                          int* length, double* timeout);
 328 enum kwsysProcess_Pipes_e
 329 {
 330   kwsysProcess_Pipe_None,
 331   kwsysProcess_Pipe_STDIN,
 332   kwsysProcess_Pipe_STDOUT,
 333   kwsysProcess_Pipe_STDERR,
 334   kwsysProcess_Pipe_Timeout=255
 335 };
 336
 337 /**
 338  * Block until the child process terminates or the given timeout
 339  * expires.  If no process is running, returns immediatly.  The
 340  * argument is:
 341  *
 342  *  timeout = Specifies the maximum time this call may block.  Upon
 343  *            returning due to child termination, the elapsed time
 344  *            is subtracted from the given value.  A NULL pointer
 345  *            passed for this argument indicates no timeout for the
 346  *            call.
 347  *
 348  * Return value will be one of:
 349  *
 350  *    0 = Child did not terminate within timeout specified for
 351  *        the call.  Time elapsed has been subtracted from timeout
 352  *        argument.
 353  *    1 = Child has terminated or was not running.
 354  */
 355 kwsysEXPORT int kwsysProcess_WaitForExit(kwsysProcess* cp, double* timeout);
 356
 357 /**
 358  * Forcefully terminate the child process that is currently running.
 359  * The caller should call WaitForExit after this returns to wait for
 360  * the child to terminate.
 361  */
 362 kwsysEXPORT void kwsysProcess_Kill(kwsysProcess* cp);
 363
 364 #if defined(__cplusplus)
 365 } /* extern "C" */
 366 #endif
 367
 368 /* If we are building a kwsys .c or .cxx file, let it use these macros.
 369    Otherwise, undefine them to keep the namespace clean.  */
 370 #if !defined(KWSYS_NAMESPACE)
 371 # undef kwsys_ns
 372 # undef kwsysEXPORT
 373 # undef kwsysProcess
 374 # undef kwsysProcess_s
 375 # undef kwsysProcess_New
 376 # undef kwsysProcess_Delete
 377 # undef kwsysProcess_SetCommand
 378 # undef kwsysProcess_AddCommand
 379 # undef kwsysProcess_SetTimeout
 380 # undef kwsysProcess_SetWorkingDirectory
 381 # undef kwsysProcess_SetPipeFile
 382 # undef kwsysProcess_SetPipeNative
 383 # undef kwsysProcess_SetPipeShared
 384 # undef kwsysProcess_Option_Detach
 385 # undef kwsysProcess_Option_HideWindow
 386 # undef kwsysProcess_Option_Verbatim
 387 # undef kwsysProcess_GetOption
 388 # undef kwsysProcess_SetOption
 389 # undef kwsysProcess_Option_e
 390 # undef kwsysProcess_State_Starting
 391 # undef kwsysProcess_State_Error
 392 # undef kwsysProcess_State_Exception
 393 # undef kwsysProcess_State_Executing
 394 # undef kwsysProcess_State_Exited
 395 # undef kwsysProcess_State_Expired
 396 # undef kwsysProcess_State_Killed
 397 # undef kwsysProcess_State_Disowned
 398 # undef kwsysProcess_GetState
 399 # undef kwsysProcess_State_e
 400 # undef kwsysProcess_Exception_None
 401 # undef kwsysProcess_Exception_Fault
 402 # undef kwsysProcess_Exception_Illegal
 403 # undef kwsysProcess_Exception_Interrupt
 404 # undef kwsysProcess_Exception_Numerical
 405 # undef kwsysProcess_Exception_Other
 406 # undef kwsysProcess_GetExitException
 407 # undef kwsysProcess_Exception_e
 408 # undef kwsysProcess_GetExitCode
 409 # undef kwsysProcess_GetExitValue
 410 # undef kwsysProcess_GetErrorString
 411 # undef kwsysProcess_GetExceptionString
 412 # undef kwsysProcess_Execute
 413 # undef kwsysProcess_Disown
 414 # undef kwsysProcess_WaitForData
 415 # undef kwsysProcess_Pipes_e
 416 # undef kwsysProcess_Pipe_None
 417 # undef kwsysProcess_Pipe_STDIN
 418 # undef kwsysProcess_Pipe_STDOUT
 419 # undef kwsysProcess_Pipe_STDERR
 420 # undef kwsysProcess_Pipe_Timeout
 421 # undef kwsysProcess_Pipe_Handle
 422 # undef kwsysProcess_WaitForExit
 423 # undef kwsysProcess_Kill
 424 #endif
 425
 426 #endif