VMSbuild/cmsys/Process.h

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