summaryrefslogtreecommitdiff
path: root/ace/Process.h
blob: 7f1685f4ef99297bb8dec8be4d92d73713065b50 (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
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
/* -*- C++ -*- */

//=============================================================================
/**
 *  @file    Process.h
 *
 *  $Id$
 *
 *  @author Tim Harrison <harrison@cs.wustl.edu>
 */
//=============================================================================

#ifndef ACE_PROCESS_H
#define ACE_PROCESS_H
#include /**/ "ace/pre.h"

#include "ace/ACE_export.h"

#if !defined (ACE_LACKS_PRAGMA_ONCE)
# pragma once
#endif /* ACE_LACKS_PRAGMA_ONCE */

#include "ace/Handle_Set.h"
#include "ace/os_include/sys/os_types.h"
#include "ace/Global_Macros.h"

// Forward declaration
class ACE_Time_Value;

/**
 * @class ACE_Process_Options
 *
 * @brief Process Options
 *
 * This class controls the options passed to <CreateProcess> (or <fork>
 * and <exec>).
 * Notice that on Windows CE, creating a process merely means
 * instantiating a new process.  You can't set the handles (since
 * there's no stdin, stdout and stderr,) specify process/thread
 * options, set environment,...  So, basically, this class only
 * set the command line and nothing else.
 * Notice that on UNIX platforms, if the <setenv> is used, the
 * <spawn> is using the <execve> system call. It means that the
 * <command_line> should include a full path to the program file
 * (<execve> does not search the PATH).  If <setenv> is not used
 * then, the <spawn> is using the <execvp> which searches for the
 * program file in the PATH variable.
 */
class ACE_Export ACE_Process_Options
{
public:
  enum
  {
    DEFAULT_COMMAND_LINE_BUF_LEN = 1024,
    // UNIX process creation flags.
#if defined (ACE_WIN32)
    NO_EXEC = 0
#else
    NO_EXEC = 1
#endif /* ACE_WIN32 */
  };

protected:
  // = Default settings not part of public Interface.
  //
  // @@todo These sizes should be taken from the appropriate
  // POSIX/system header files and/or defined dynamically.
  enum
  {
    MAX_COMMAND_LINE_OPTIONS = 128,
    ENVIRONMENT_BUFFER = 16 * 1024, // 16K
    MAX_ENVIRONMENT_ARGS = 512 //
  };

public:
  /**
   * If <inherit_environment> == 1, the new process will inherit the
   * environment of the current process.  <command_line_buf_len> is the
   * max strlen for command-line arguments.
   */
  ACE_Process_Options (int inherit_environment = 1,
                       int command_line_buf_len = DEFAULT_COMMAND_LINE_BUF_LEN,
                       int env_buf_len = ENVIRONMENT_BUFFER,
                       int max_env_args = MAX_ENVIRONMENT_ARGS);

  /// Destructor.
  ~ACE_Process_Options (void);

  // = Methods to set process creation options portably.

  /**
   * Set the standard handles of the new process to the respective
   * handles.  If you want to affect a subset of the handles, make
   * sure to set the others to ACE_INVALID_HANDLE.  Returns 0 on
   * success, -1 on failure.
   */
  int set_handles (ACE_HANDLE std_in,
                   ACE_HANDLE std_out = ACE_INVALID_HANDLE,
                   ACE_HANDLE std_err = ACE_INVALID_HANDLE);

  /// Release the standard handles previously set with set_handles;
  void release_handles (void);

  /// @param format must be of the form "VARIABLE=VALUE".  There can not be
  /// any spaces between VARIABLE and the equal sign.
  int setenv (const ACE_TCHAR *format,
              ...);

  /**
   * Set a single environment variable, <variable_name>.  Since
   * different platforms separate each environment variable
   * differently, you must call this method once for each variable.
   * <format> can be any printf format string.  So options->setenv
   * ("FOO","one + two = %s", "three") will result in "FOO=one + two =
   * three".
   */
  int setenv (const ACE_TCHAR *variable_name,
              const ACE_TCHAR *format,
              ...);

  /// Same as above with argv format.  <envp> must be null terminated.
  int setenv (ACE_TCHAR *envp[]);

  /// Set the working directory for the process.  strlen of <wd> must
  /// be <= MAXPATHLEN.
  void working_directory (const char *wd);

#if defined (ACE_HAS_WCHAR)
  /// wchar_t version of working_directory
  void working_directory (const wchar_t *wd);
#endif /* ACE_HAS_WCHAR */

  /**
   * Set the command-line arguments.  <format> can use any printf
   * formats.  The first token in <format> should be the path to the
   * application.  This can either be a full path, relative path, or
   * just an executable name.  If an executable name is used, we rely
   * on the platform's support for searching paths.  Since we need a
   * path to run a process, this method *must* be called!  Returns 0
   * on success, -1 on failure.
   */
  int command_line (const ACE_TCHAR *format, ...);

#if defined (ACE_HAS_WCHAR) && !defined (ACE_HAS_WINCE)
  /// Anti-TChar version of command_line ()
  int command_line (const ACE_ANTI_TCHAR *format, ...);
#endif /* ACE_HAS_WCHAR && !ACE_HAS_WINCE */

  /// Same as above in argv format.  <argv> must be null terminated.
  int command_line (const ACE_TCHAR * const argv[]);

  // = Set/get the pathname used to name the process.
  /**
   * Specify the full path or relative path, or just the executable
   * name for the process. If this is set, then <name> will be used to
   * create the process instead of argv[0] set in the command
   * line. This is here so that you can supply something other than
   * executable name as argv[0].
   */
  void process_name (const ACE_TCHAR *name);

  /// Return the process_name.  If the <process_name(name)> set
  /// method is not called, this method will return argv[0].
  const ACE_TCHAR *process_name (void);

  // = Set/get creation flags.
  /// Get the creation flags.
  u_long creation_flags (void) const;

  /// Set the creation flags.
  void creation_flags (u_long);

  // = <ACE_Process> uses these operations to retrieve option values.

  /// Current working directory.  Returns "" if nothing has been set.
  ACE_TCHAR *working_directory (void);

  /// Buffer of command-line options.  Returns a pointer to a buffer that
  /// contains the list of command line options.  Prior to a call to
  /// command_line_argv(), this is a single string of space separated
  /// arguments independent of which form of command_line() was used to
  /// create it.  After a call to command_line_argv(), this is a list of
  /// strings each terminated by '\0'.  [Note: spawn() will call
  /// command_line_argv().]  The total length of all these strings is the
  /// same as the single string in the prior case and can be obtained by
  /// providing max_len. @arg max_len, if non-zero, provides a location
  /// into which the total length of the command line buffer is returned.
  ACE_TCHAR *command_line_buf (int *max_len = 0);

  /**
   * argv-style command-line options.  Parses and modifies the string
   * created from <command_line_>.  All spaces not in quotes ("" or
   * '') are replaced with null (\0) bytes.  An argv array is built
   * and returned with each entry pointing to the start of
   * null-terminated string.  Returns { 0 } if nothing has been set.
   */
  ACE_TCHAR * const *command_line_argv (void);

  /**
   * Null-terminated buffer of null terminated strings.  Each string
   * is an environment assignment "VARIABLE=value".  This buffer
   * should end with two null characters.
   */
  ACE_TCHAR *env_buf (void);

  // = Get/set process group.
  /// Get the process group.  On UNIX, these methods are used by the
  /// <ACE_Process_Manager> to manage groups of processes.
  pid_t getgroup (void) const;

  /// Set the process group.  On UNIX, these methods are used by the
  /// <ACE_Process_Manager> to manage groups of processes.
  pid_t setgroup (pid_t pgrp);

  /// Default is TRUE.
  /// Allows disabling of handle inheritence.
  int handle_inheritence (void);
  void handle_inheritence (int);

  /// Cause the specified handle to be passed to a child process
  /// when it runs a new program image.
  /**
   * The specified handle value will be included in the spawned
   * process's command line as @arg +H @arg handle, if a new
   * program is spawned (always on Win32; else if NO_EXEC is not
   * set in creation flags).  The passed handle value will be
   * duplicated if on Win32 less capable than NT.
   * @return 0 if success, -1 if failure.
   */
  int pass_handle (ACE_HANDLE);

  /// Get a copy of the handles the ACE_Process_Options duplicated
  /// for the spawned process.
  /**
   * Any handles created through duplication of those passed into
   * @arg pass_handle are returned in @arg set.
   * @return 0 if there were no handles to return; 1 if there were.
   */
  int dup_handles (ACE_Handle_Set &set) const;

  /// Get a copy of the handles passed to the spawned process. This
  /// will be the set of handles previously passed to @arg pass_handle().
  /**
   * Any handles previously passed to @arg pass_handle are returned
   * in @arg set.
   * @return 0 if there were no handles to return; 1 if there were.
   */
  int passed_handles (ACE_Handle_Set &set) const;

  /// Set value for avoid_zombies (has no real effect except on *nix).
  void avoid_zombies (int);

  /// Get current value for avoid_zombies.
  int avoid_zombies (void);

#if defined (ACE_WIN32)
  // = Non-portable accessors for when you "just have to use them."

  /// Used for setting and getting.
  ACE_TEXT_STARTUPINFO *startup_info (void);

  /// Get the process_attributes.  Returns NULL if
  /// set_process_attributes has not been set.
  LPSECURITY_ATTRIBUTES get_process_attributes (void) const;

  /// If this is called, a non-null process attributes is sent to
  /// CreateProcess.
  LPSECURITY_ATTRIBUTES set_process_attributes (void);

  /// Get the thread_attributes.  Returns NULL if set_thread_attributes
  /// has not been set.
  LPSECURITY_ATTRIBUTES get_thread_attributes (void) const;

  /// If this is called, a non-null thread attributes is sent to
  /// CreateProcess.
  LPSECURITY_ATTRIBUTES set_thread_attributes (void);

#else /* All things not WIN32 */

  /// argv-style array of environment settings.
  ACE_TCHAR *const *env_argv (void);

  // = Accessors for the standard handles.
  ACE_HANDLE get_stdin (void) const;
  ACE_HANDLE get_stdout (void) const;
  ACE_HANDLE get_stderr (void) const;

  // = Set/get real & effective user & group id associated with user.
  int setreugid (const ACE_TCHAR* user);
  void setruid (uid_t id);
  void seteuid (uid_t id);
  void setrgid (uid_t id);
  void setegid (uid_t id);
  uid_t getruid (void) const;
  uid_t geteuid (void) const;
  uid_t getrgid (void) const;
  uid_t getegid (void) const;

  /**
   * Get the inherit_environment flag.
   */
  int inherit_environment (void) const;

  /**
   * Set the inherit_environment flag.
   */
  void inherit_environment (int nv);
#endif /* ACE_WIN32 */
protected:

#if !defined (ACE_HAS_WINCE)
  /// Add <assignment> to environment_buf_ and adjust
  /// environment_argv_.  <len> is the strlen of <assignment>.
  int setenv_i (ACE_TCHAR *assignment, size_t len);

  /// Whether the child process inherits the current process
  /// environment.
  int inherit_environment_;
#endif /* !ACE_HAS_WINCE */

  /// Default 0.
  u_long creation_flags_;

  /// Avoid zombies for spawned processes.
  int avoid_zombies_;

#if defined (ACE_WIN32) && !defined (ACE_HAS_WINCE)
  /// Helper function to grab win32 environment and stick it in
  /// environment_buf_ using this->setenv_i.
  void inherit_environment (void);

  /// Ensures once only call to inherit environment.
  int environment_inherited_;

  ACE_TEXT_STARTUPINFO startup_info_;

  /// Default TRUE.
  BOOL handle_inheritence_;

  /// Pointer to security_buf1_.
  LPSECURITY_ATTRIBUTES process_attributes_;

  /// Pointer to security_buf2_.
  LPSECURITY_ATTRIBUTES thread_attributes_;

  /// Data for process_attributes_.
  SECURITY_ATTRIBUTES security_buf1_;

  /// Data for thread_attributes_.
  SECURITY_ATTRIBUTES security_buf2_;

#else /* !ACE_WIN32 */
  ACE_HANDLE stdin_;
  ACE_HANDLE stdout_;
  ACE_HANDLE stderr_;

  // = Real & effective user & group id's.
  //   These should be set to -1 to leave unchanged (default).
  uid_t ruid_;
  uid_t euid_;
  uid_t rgid_;
  uid_t egid_;
#endif /* ACE_WIN32 */

#if !defined (ACE_HAS_WINCE)
  /// Is 1 if stdhandles was called.
  int set_handles_called_;

  /// Pointer into environment_buf_.  This should point to the next
  /// free spot.
  size_t environment_buf_index_;

  /// Pointer to environment_argv_.
  int environment_argv_index_;

  /// Pointer to buffer of the environment settings.
  ACE_TCHAR *environment_buf_;

  /// Size of the environment buffer. Configurable
  size_t environment_buf_len_;

  /// Pointers into environment_buf_.
  ACE_TCHAR **environment_argv_;

  /// Maximum number of environment variables. Configurable
  int max_environment_args_;

  /// Maximum index of environment_argv_ buffer
  int max_environ_argv_index_;

  /// The current working directory.
  ACE_TCHAR working_directory_[MAXPATHLEN + 1];
#endif /* !ACE_HAS_WINCE */

  /// Ensures command_line_argv is only calculated once.
  int command_line_argv_calculated_;

  /// Pointer to buffer of command-line arguments.  E.g., "-f foo -b bar".
  ACE_TCHAR *command_line_buf_;

  /// Pointer to copy of command-line arguments, which is needed when
  /// converting a command-line string into a command-line argv.
  ACE_TCHAR *command_line_copy_;

  /// Max length of command_line_buf_
  int command_line_buf_len_;

  /// Argv-style command-line arguments.
  ACE_TCHAR *command_line_argv_[MAX_COMMAND_LINE_OPTIONS];

  /// Process-group on Unix; unused on Win32.
  pid_t process_group_;

  /// Set of handles that were passed in pass_handle ().
  ACE_Handle_Set handles_passed_;

  /// Results of duplicating handles passed in pass_handle ().
  ACE_Handle_Set dup_handles_;

  /// Pathname for the process. Relative path or absolute path or just
  /// the program name.
  ACE_TCHAR process_name_[MAXPATHLEN + 1];
};

//class ACE_Process_Manager;

/**
 * @class ACE_Process
 *
 * @brief Process
 *
 * A Portable encapsulation for creating new processes.
 * Notice that on UNIX platforms, if the <setenv> is used, the
 * <spawn> is using the <execve> system call. It means that the
 * <command_line> should include a full path to the program file
 * (<execve> does not search the PATH).  If <setenv> is not used
 * then, the <spawn> is using the <execvp> which searches for the
 * program file in the PATH variable.
 */
class ACE_Export ACE_Process
{
public:
  friend class ACE_Process_Manager;

  /// Default construction.  Must use <ACE_Process::spawn> to start.
  ACE_Process (void);

  /// Destructor.
  virtual ~ACE_Process (void);

  /**
   * Called just before <ACE_OS::fork> in the <spawn>.  If this
   * returns non-zero, the <spawn> is aborted (and returns
   * ACE_INVALID_PID).  The default simply returns zero.
   */
  virtual int prepare (ACE_Process_Options &options);

  /**
   * Launch a new process as described by <options>.  Returns the
   * process id of the newly spawned child on success or -1 on
   * failure.
   */
  virtual pid_t spawn (ACE_Process_Options &options);

  /// Called just after <ACE_OS::fork> in the parent's context, if the
  /// <fork> succeeds.  The default is to do nothing.
  virtual void parent (pid_t child);

  /**
   * Called just after <ACE_OS::fork> in the child's context.  The
   * default does nothing.  This function is *not* called on Win32
   * because the process-creation scheme does not allow it.
   */
  virtual void child (pid_t parent);

  /// Called by a <Process_Manager> that is removing this Process from
  /// its table of managed Processes.  Default is to do nothing.
  virtual void unmanage (void);

  /**
   * Wait for the process we've created to exit.  If <status> != 0, it
   * points to an integer where the function store the exit status of
   * child process to.  If <wait_options> == <WNOHANG> then return 0
   * and don't block if the child process hasn't exited yet.  A return
   * value of -1 represents the <wait> operation failed, otherwise,
   * the child process id is returned.
   */
  pid_t wait (ACE_exitcode *status = 0,
              int wait_options = 0);

  /**
   * Timed wait for the process we've created to exit.  A return value
   * of -1 indicates that the something failed; 0 indicates that a
   * timeout occurred.  Otherwise, the child's process id is returned.
   * If <status> != 0, it points to an integer where the function
   * stores the child's exit status.
   *
   * NOTE: on UNIX platforms this function uses <ualarm>, i.e., it
   * overwrites any existing alarm.  In addition, it steals all
   * <SIGCHLD>s during the timeout period, which will break another
   * <ACE_Process_Manager> in the same process that's expecting
   * <SIGCHLD> to kick off process reaping.
   */
  pid_t wait (const ACE_Time_Value &tv,
              ACE_exitcode *status = 0);

  /// Send the process a signal.  This is only portable to operating
  /// systems that support signals, such as UNIX/POSIX.
  int kill (int signum = SIGINT);

  /**
   * Terminate the process abruptly using <ACE::terminate_process>.
   * This call doesn't give the process a chance to cleanup, so use it
   * with caution...
   */
  int terminate (void);

  /// Return the process id of the new child process.
  pid_t getpid (void) const;

  /// Return the handle of the process, if it has one.
  ACE_HANDLE gethandle (void) const;

  /// Return 1 if running; 0 otherwise.
  int running (void) const;

  /// Return the Process' exit code.  This method returns the raw
  /// exit status returned from system APIs (such as <wait> or
  /// <waitpid>).  This value is system dependent.
  ACE_exitcode exit_code (void) const;

  /// Return the Process' return value.  This method returns the
  /// actual return value that a child process returns or <exit>s.
  int return_value (void) const;

  /// Close all the handles in the set obtained from the
  /// @arg ACE_Process_Options::dup_handles object used to spawn
  /// the process.
  void close_dup_handles (void);

  /// Close all the handles in the set obtained from the
  /// @arg ACE_Process_Options::passed_handles object used to spawn
  /// the process.
  void close_passed_handles (void);

#if defined (ACE_WIN32)
  PROCESS_INFORMATION process_info (void);
#endif /* ACE_WIN32 */

protected:
  /// Set this process' <exit_code_>.  ACE_Process_Manager uses this
  /// method to set the <exit_code_> after successfully waiting for
  /// this proecess to exit.
  void exit_code (ACE_exitcode code);

#if defined (ACE_WIN32)
  PROCESS_INFORMATION process_info_;
#else /* ACE_WIN32 */
  /// Process id of the child.
  pid_t child_id_;
#endif /* ACE_WIN32 */
  ACE_exitcode exit_code_;

  /// Set of handles that were passed to the child process.
  ACE_Handle_Set handles_passed_;
  /// Handle duplicates made for the child process.
  ACE_Handle_Set dup_handles_;

  // = Disallow copying and assignment since we don't support this (yet).
  ACE_UNIMPLEMENTED_FUNC (ACE_Process (const ACE_Process &))
  ACE_UNIMPLEMENTED_FUNC (void operator= (const ACE_Process &))
};


/**
 * @class ACE_Managed_Process
 *
 * @brief A process easily managed by ACE_Process_Manager.
 *
 * @arg ACE_Managed_Process is just an @arg ACE_Process with an
 * @arg unmanage method that deletes the instance.
 * This class is only valid for use as a dynamically-allocated object!
 */
class ACE_Export ACE_Managed_Process : public ACE_Process
{
public:
  ACE_Managed_Process ();

  /// Cleanup by deleting <this>.
  virtual void unmanage (void);

private:
  /// Make sure that we're allocated dynamically!
  virtual ~ACE_Managed_Process (void);

  /// Keep G++ happy...
  friend class ace_dewarn_gplusplus;
};

#include "ace/SString.h"

#if defined (__ACE_INLINE__)
#include "ace/Process.inl"
#endif /* __ACE_INLINE__ */

#include /**/ "ace/post.h"
#endif /* ACE_PROCESS_H */