summaryrefslogtreecommitdiffstats
path: root/Source/kwsys/Process.h.in
blob: c5ebc97f4f53790077b6197d3706ff9a4f3cffed (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
/*============================================================================
  KWSys - Kitware System Library
  Copyright 2000-2009 Kitware, Inc., Insight Software Consortium

  Distributed under the OSI-approved BSD License (the "License");
  see accompanying file Copyright.txt for details.

  This software is distributed WITHOUT ANY WARRANTY; without even the
  implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  See the License 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.  */
#if !defined(KWSYS_NAMESPACE)
# define kwsys_ns(x) @KWSYS_NAMESPACE@##x
# define kwsysEXPORT @KWSYS_NAMESPACE@_EXPORT
#endif
#if !@KWSYS_NAMESPACE@_NAME_IS_KWSYS
# define kwsysProcess                           kwsys_ns(Process)
# define kwsysProcess_s                         kwsys_ns(Process_s)
# define kwsysProcess_New                       kwsys_ns(Process_New)
# define kwsysProcess_Delete                    kwsys_ns(Process_Delete)
# define kwsysProcess_SetCommand                kwsys_ns(Process_SetCommand)
# define kwsysProcess_AddCommand                kwsys_ns(Process_AddCommand)
# define kwsysProcess_SetTimeout                kwsys_ns(Process_SetTimeout)
# define kwsysProcess_SetWorkingDirectory       kwsys_ns(Process_SetWorkingDirectory)
# define kwsysProcess_SetPipeFile               kwsys_ns(Process_SetPipeFile)
# define kwsysProcess_SetPipeNative             kwsys_ns(Process_SetPipeNative)
# define kwsysProcess_SetPipeShared             kwsys_ns(Process_SetPipeShared)
# define kwsysProcess_Option_Detach             kwsys_ns(Process_Option_Detach)
# define kwsysProcess_Option_HideWindow         kwsys_ns(Process_Option_HideWindow)
# define kwsysProcess_Option_MergeOutput        kwsys_ns(Process_Option_MergeOutput)
# define kwsysProcess_Option_Verbatim           kwsys_ns(Process_Option_Verbatim)
# define kwsysProcess_Option_CreateProcessGroup kwsys_ns(Process_Option_CreateProcessGroup)
# define kwsysProcess_GetOption                 kwsys_ns(Process_GetOption)
# define kwsysProcess_SetOption                 kwsys_ns(Process_SetOption)
# define kwsysProcess_Option_e                  kwsys_ns(Process_Option_e)
# define kwsysProcess_State_Starting            kwsys_ns(Process_State_Starting)
# define kwsysProcess_State_Error               kwsys_ns(Process_State_Error)
# define kwsysProcess_State_Exception           kwsys_ns(Process_State_Exception)
# define kwsysProcess_State_Executing           kwsys_ns(Process_State_Executing)
# define kwsysProcess_State_Exited              kwsys_ns(Process_State_Exited)
# define kwsysProcess_State_Expired             kwsys_ns(Process_State_Expired)
# define kwsysProcess_State_Killed              kwsys_ns(Process_State_Killed)
# define kwsysProcess_State_Disowned            kwsys_ns(Process_State_Disowned)
# define kwsysProcess_GetState                  kwsys_ns(Process_GetState)
# define kwsysProcess_State_e                   kwsys_ns(Process_State_e)
# define kwsysProcess_Exception_None            kwsys_ns(Process_Exception_None)
# define kwsysProcess_Exception_Fault           kwsys_ns(Process_Exception_Fault)
# define kwsysProcess_Exception_Illegal         kwsys_ns(Process_Exception_Illegal)
# define kwsysProcess_Exception_Interrupt       kwsys_ns(Process_Exception_Interrupt)
# define kwsysProcess_Exception_Numerical       kwsys_ns(Process_Exception_Numerical)
# define kwsysProcess_Exception_Other           kwsys_ns(Process_Exception_Other)
# define kwsysProcess_GetExitException          kwsys_ns(Process_GetExitException)
# define kwsysProcess_Exception_e               kwsys_ns(Process_Exception_e)
# define kwsysProcess_GetExitCode               kwsys_ns(Process_GetExitCode)
# define kwsysProcess_GetExitValue              kwsys_ns(Process_GetExitValue)
# define kwsysProcess_GetErrorString            kwsys_ns(Process_GetErrorString)
# define kwsysProcess_GetExceptionString        kwsys_ns(Process_GetExceptionString)
# define kwsysProcess_Execute                   kwsys_ns(Process_Execute)
# define kwsysProcess_Disown                    kwsys_ns(Process_Disown)
# define kwsysProcess_WaitForData               kwsys_ns(Process_WaitForData)
# define kwsysProcess_Pipes_e                   kwsys_ns(Process_Pipes_e)
# define kwsysProcess_Pipe_None                 kwsys_ns(Process_Pipe_None)
# define kwsysProcess_Pipe_STDIN                kwsys_ns(Process_Pipe_STDIN)
# define kwsysProcess_Pipe_STDOUT               kwsys_ns(Process_Pipe_STDOUT)
# define kwsysProcess_Pipe_STDERR               kwsys_ns(Process_Pipe_STDERR)
# define kwsysProcess_Pipe_Timeout              kwsys_ns(Process_Pipe_Timeout)
# define kwsysProcess_Pipe_Handle               kwsys_ns(Process_Pipe_Handle)
# define kwsysProcess_WaitForExit               kwsys_ns(Process_WaitForExit)
# define kwsysProcess_Interrupt                 kwsys_ns(Process_Interrupt)
# define kwsysProcess_Kill                      kwsys_ns(Process_Kill)
#endif

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

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

/* Platform-specific pipe handle type.  */
#if defined(_WIN32) && !defined(__CYGWIN__)
typedef void* kwsysProcess_Pipe_Handle;
#else
typedef int kwsysProcess_Pipe_Handle;
#endif

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

/**
 * 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.  The 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.  The 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 in seconds 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.
 * Returns 1 for success and 0 for failure.
 */
kwsysEXPORT int kwsysProcess_SetWorkingDirectory(kwsysProcess* cp,
                                                 const char* dir);

/**
 * Set the name of a file to be attached to the given pipe.  Returns 1
 * for success and 0 for failure.
 */
kwsysEXPORT int kwsysProcess_SetPipeFile(kwsysProcess* cp, int pipe,
                                         const char* file);

/**
 * Set whether the given pipe in the child is shared with the parent
 * process.  The default is no for Pipe_STDOUT and Pipe_STDERR and yes
 * for Pipe_STDIN.
 */
kwsysEXPORT void kwsysProcess_SetPipeShared(kwsysProcess* cp, int pipe,
                                            int shared);

/**
 * Specify a platform-specific native pipe for use as one of the child
 * interface pipes.  The native pipe is specified by an array of two
 * descriptors or handles.  The first entry in the array (index 0)
 * should be the read end of the pipe.  The second entry in the array
 * (index 1) should be the write end of the pipe.  If a null pointer
 * is given the option will be disabled.
 *
 * For Pipe_STDIN the native pipe is connected to the first child in
 * the pipeline as its stdin.  After the children are created the
 * write end of the pipe will be closed in the child process and the
 * read end will be closed in the parent process.
 *
 * For Pipe_STDOUT and Pipe_STDERR the pipe is connected to the last
 * child as its stdout or stderr.  After the children are created the
 * write end of the pipe will be closed in the parent process and the
 * read end will be closed in the child process.
 */
kwsysEXPORT void kwsysProcess_SetPipeNative(kwsysProcess* cp, int pipe,
                                            kwsysProcess_Pipe_Handle p[2]);

/**
 * Get/Set a possibly platform-specific option.  Possible options are:
 *
 *  kwsysProcess_Option_Detach = Whether to detach the process.
 *         0 = No (default)
 *         1 = Yes
 *
 *  kwsysProcess_Option_HideWindow = Whether to hide window on Windows.
 *         0 = No (default)
 *         1 = Yes
 *
 *  kwsysProcess_Option_MergeOutput = Whether to merge stdout/stderr.
 *                                    No content will be returned as stderr.
 *                                    Any actual stderr will be on stdout.
 *         0 = No (default)
 *         1 = Yes
 *
 *  kwsysProcess_Option_Verbatim = Whether SetCommand and AddCommand
 *                                 should treat the first argument
 *                                 as a verbatim command line
 *                                 and ignore the rest of the arguments.
 *         0 = No (default)
 *         1 = Yes
 *
 *  kwsysProcess_Option_CreateProcessGroup = Whether to place the process in a
 *                                           new process group.  This is
 *                                           useful if you want to send Ctrl+C
 *                                           to the process.  On UNIX, also
 *                                           places the process in a new
 *                                           session.
 *         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,
  kwsysProcess_Option_Detach,
  kwsysProcess_Option_MergeOutput,
  kwsysProcess_Option_Verbatim,
  kwsysProcess_Option_CreateProcessGroup
};

/**
 * 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.
 *  kwsysProcess_State_Disowned  = Child is no longer managed by this object.
 */
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,
  kwsysProcess_State_Disowned
};

/**
 * 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);

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

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

/**
 * Stop management of a detached child process.  This closes any pipes
 * being read.  If the child was not created with the
 * kwsysProcess_Option_Detach option, this method does nothing.  This
 * is because disowning a non-detached process will cause the child
 * exit signal to be left unhandled until this process exits.
 */
kwsysEXPORT void kwsysProcess_Disown(kwsysProcess* cp);

/**
 * Block until data are available on a pipe, a timeout expires, or the
 * child process terminates.  Arguments are as follows:
 *
 *  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.  A negative or zero
 *            value passed for this argument may be used for polling
 *            and will always return immediately.
 *
 * Return value will be one of:
 *
 *   Pipe_None    = No more data will be available from the child process,
 *    ( == 0)       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, char** data,
                                         int* length, double* timeout);
enum kwsysProcess_Pipes_e
{
  kwsysProcess_Pipe_None,
  kwsysProcess_Pipe_STDIN,
  kwsysProcess_Pipe_STDOUT,
  kwsysProcess_Pipe_STDERR,
  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);

/**
 * Interrupt the process group for the child process that is currently
 * running by sending it the appropriate operating-system specific signal.
 * The caller should call WaitForExit after this returns to wait for the
 * child to terminate.
 *
 * WARNING:  If you didn't specify kwsysProcess_Option_CreateProcessGroup,
 * you will interrupt your own process group.
 */
kwsysEXPORT void kwsysProcess_Interrupt(kwsysProcess* cp);

/**
 * 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 kwsys .c or .cxx file, let it use these macros.
   Otherwise, undefine them to keep the namespace clean.  */
#if !defined(KWSYS_NAMESPACE)
# undef kwsys_ns
# undef kwsysEXPORT
# if !@KWSYS_NAMESPACE@_NAME_IS_KWSYS
#  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_SetPipeFile
#  undef kwsysProcess_SetPipeNative
#  undef kwsysProcess_SetPipeShared
#  undef kwsysProcess_Option_Detach
#  undef kwsysProcess_Option_HideWindow
#  undef kwsysProcess_Option_MergeOutput
#  undef kwsysProcess_Option_Verbatim
#  undef kwsysProcess_Option_CreateProcessGroup
#  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_State_Disowned
#  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_GetExceptionString
#  undef kwsysProcess_Execute
#  undef kwsysProcess_Disown
#  undef kwsysProcess_WaitForData
#  undef kwsysProcess_Pipes_e
#  undef kwsysProcess_Pipe_None
#  undef kwsysProcess_Pipe_STDIN
#  undef kwsysProcess_Pipe_STDOUT
#  undef kwsysProcess_Pipe_STDERR
#  undef kwsysProcess_Pipe_Timeout
#  undef kwsysProcess_Pipe_Handle
#  undef kwsysProcess_WaitForExit
#  undef kwsysProcess_Interrupt
#  undef kwsysProcess_Kill
# endif
#endif

#endif