00001 // -*- C++ -*- 00002 00003 //============================================================================= 00004 /** 00005 * @file Process.h 00006 * 00007 * $Id: Process.h 91233 2010-07-29 14:47:16Z shuston $ 00008 * 00009 * @author Tim Harrison <harrison@cs.wustl.edu> 00010 */ 00011 //============================================================================= 00012 00013 #ifndef ACE_PROCESS_H 00014 #define ACE_PROCESS_H 00015 00016 #include /**/ "ace/pre.h" 00017 00018 #include /**/ "ace/ACE_export.h" 00019 00020 #if !defined (ACE_LACKS_PRAGMA_ONCE) 00021 # pragma once 00022 #endif /* ACE_LACKS_PRAGMA_ONCE */ 00023 00024 #include "ace/Handle_Set.h" 00025 #include "ace/Global_Macros.h" 00026 #include "ace/os_include/sys/os_types.h" 00027 00028 ACE_BEGIN_VERSIONED_NAMESPACE_DECL 00029 00030 // Forward declaration 00031 class ACE_Time_Value; 00032 00033 /** 00034 * @class ACE_Process_Options 00035 * 00036 * @brief Process Options 00037 * 00038 * This class controls the options passed to <CreateProcess> (or <fork> 00039 * and <exec>). 00040 * Notice that on Windows CE, creating a process merely means 00041 * instantiating a new process. You can't set the handles (since 00042 * there's no stdin, stdout and stderr,) specify process/thread 00043 * options, set environment,... So, basically, this class only 00044 * set the command line and nothing else. 00045 * Notice that on UNIX platforms, if the <setenv> is used, the 00046 * <spawn> is using the <execve> system call. It means that the 00047 * <command_line> should include a full path to the program file 00048 * (<execve> does not search the PATH). If <setenv> is not used 00049 * then, the <spawn> is using the <execvp> which searches for the 00050 * program file in the PATH variable. 00051 */ 00052 class ACE_Export ACE_Process_Options 00053 { 00054 public: 00055 enum 00056 { 00057 DEFAULT_COMMAND_LINE_BUF_LEN = 1024, 00058 // UNIX process creation flags. 00059 #if defined (ACE_WIN32) 00060 NO_EXEC = 0 00061 #else 00062 NO_EXEC = 1 00063 #endif /* ACE_WIN32 */ 00064 }; 00065 00066 protected: 00067 // = Default settings not part of public Interface. 00068 // 00069 /// @todo These sizes should be taken from the appropriate 00070 /// POSIX/system header files and/or defined dynamically. 00071 enum 00072 { 00073 MAX_COMMAND_LINE_OPTIONS = 128, 00074 ENVIRONMENT_BUFFER = 16 * 1024, // 16K 00075 MAX_ENVIRONMENT_ARGS = 512 // 00076 }; 00077 00078 public: 00079 /** 00080 * If @a inherit_environment == true, the new process will inherit the 00081 * environment of the current process. @a command_line_buf_len is the 00082 * max strlen for command-line arguments. 00083 */ 00084 ACE_Process_Options (bool inherit_environment = true, 00085 size_t command_line_buf_len = DEFAULT_COMMAND_LINE_BUF_LEN, 00086 size_t env_buf_len = ENVIRONMENT_BUFFER, 00087 size_t max_env_args = MAX_ENVIRONMENT_ARGS); 00088 00089 /// Destructor. 00090 ~ACE_Process_Options (void); 00091 00092 // = Methods to set process creation options portably. 00093 00094 /** 00095 * Set the standard handles of the new process to the respective 00096 * handles. If you want to affect a subset of the handles, make 00097 * sure to set the others to ACE_INVALID_HANDLE. 00098 * 00099 * @note Any handle passed as ACE_INVALID_HANDLE will be changed to 00100 * a duplicate of the current associated handle. For example, passing 00101 * ACE_INVALID_HANDLE for @a std_in will cause ACE_STDIN to be 00102 * duplicated and set in this object. 00103 * 00104 * @return 0 on success, -1 on failure. 00105 */ 00106 int set_handles (ACE_HANDLE std_in, 00107 ACE_HANDLE std_out = ACE_INVALID_HANDLE, 00108 ACE_HANDLE std_err = ACE_INVALID_HANDLE); 00109 00110 /// Release the standard handles previously set with set_handles; 00111 void release_handles (void); 00112 00113 /// @param format must be of the form "VARIABLE=VALUE". There can not be 00114 /// any spaces between VARIABLE and the equal sign. 00115 int setenv (const ACE_TCHAR *format, 00116 ...); 00117 00118 /** 00119 * Set a single environment variable, @a variable_name. Since 00120 * different platforms separate each environment variable 00121 * differently, you must call this method once for each variable. 00122 * @a format can be any printf format string. So options->setenv 00123 * ("FOO","one + two = %s", "three") will result in "FOO=one + two = 00124 * three". 00125 */ 00126 int setenv (const ACE_TCHAR *variable_name, 00127 const ACE_TCHAR *format, 00128 ...); 00129 00130 /// Same as above with argv format. @a envp must be null terminated. 00131 int setenv (ACE_TCHAR *envp[]); 00132 00133 /// Set the working directory for the process. strlen of @a wd must 00134 /// be <= MAXPATHLEN. 00135 void working_directory (const char *wd); 00136 00137 #if defined (ACE_HAS_WCHAR) 00138 /// wchar_t version of working_directory 00139 void working_directory (const wchar_t *wd); 00140 #endif /* ACE_HAS_WCHAR */ 00141 00142 /** 00143 * Set the command-line arguments. @a format can use any printf 00144 * formats. The first token in @a format should be the path to the 00145 * application. This can either be a full path, relative path, or 00146 * just an executable name. If an executable name is used, we rely 00147 * on the platform's support for searching paths. Since we need a 00148 * path to run a process, this method *must* be called! Returns 0 00149 * on success, -1 on failure. 00150 */ 00151 int command_line (const ACE_TCHAR *format, ...); 00152 00153 #if defined (ACE_HAS_WCHAR) && !defined (ACE_HAS_WINCE) 00154 /// Anti-TChar version of command_line () 00155 int command_line (const ACE_ANTI_TCHAR *format, ...); 00156 #endif /* ACE_HAS_WCHAR && !ACE_HAS_WINCE */ 00157 00158 /// Same as above in argv format. @a argv must be null terminated. 00159 int command_line (const ACE_TCHAR * const argv[]); 00160 00161 /** 00162 * Specify the full path or relative path, or just the executable 00163 * name for the process. If this is set, then @a name will be used to 00164 * create the process instead of argv[0] set in the command 00165 * line. This is here so that you can supply something other than 00166 * executable name as argv[0]. 00167 */ 00168 void process_name (const ACE_TCHAR *name); 00169 00170 /// Return the process_name. If the <process_name(name)> set 00171 /// method is not called, this method will return argv[0]. 00172 const ACE_TCHAR *process_name (void); 00173 00174 /// Get the creation flags. 00175 u_long creation_flags (void) const; 00176 00177 /** 00178 * Set the creation flags to affect how a new process is spawned. 00179 * The only ACE-defined flag is @c NO_EXEC which prevents the new process 00180 * from executing a new program image; this is a simple POSIX fork(). 00181 * The @c NO_EXEC option has no affect on Windows; on other platforms where 00182 * a POSIX fork is not possible, specifying @c NO_EXEC will cause 00183 * ACE_Process::spawn() to fail. 00184 * 00185 * On Windows, the value of creation_flags is passed to the @c CreateProcess 00186 * system call as the value of the @c dwCreationFlags parameter. 00187 */ 00188 void creation_flags (u_long); 00189 00190 /// Current working directory. Returns "" if nothing has been set. 00191 ACE_TCHAR *working_directory (void); 00192 00193 /// Buffer of command-line options. Returns a pointer to a buffer that 00194 /// contains the list of command line options. Prior to a call to 00195 /// command_line_argv(), this is a single string of space separated 00196 /// arguments independent of which form of command_line() was used to 00197 /// create it. After a call to command_line_argv(), this is a list of 00198 /// strings each terminated by '\0'. [Note: spawn() will call 00199 /// command_line_argv().] The total length of all these strings is the 00200 /// same as the single string in the prior case and can be obtained by 00201 /// providing max_len. @arg max_len, if non-zero, provides a location 00202 /// into which the total length of the command line buffer is returned. 00203 ACE_TCHAR *command_line_buf (int *max_len = 0); 00204 00205 /** 00206 * argv-style command-line options. Parses and modifies the string 00207 * created from <command_line_>. All spaces not in quotes ("" or 00208 * '') are replaced with null (\0) bytes. An argv array is built 00209 * and returned with each entry pointing to the start of 00210 * null-terminated string. Returns { 0 } if nothing has been set. 00211 */ 00212 ACE_TCHAR * const *command_line_argv (void); 00213 00214 /** 00215 * Null-terminated buffer of null terminated strings. Each string 00216 * is an environment assignment "VARIABLE=value". This buffer 00217 * should end with two null characters. 00218 */ 00219 ACE_TCHAR *env_buf (void); 00220 00221 /// Get the process group. On UNIX, these methods are used by the 00222 /// ACE_Process_Manager to manage groups of processes. 00223 pid_t getgroup (void) const; 00224 00225 /// Set the process group. On UNIX, these methods are used by the 00226 /// ACE_Process_Manager to manage groups of processes. 00227 pid_t setgroup (pid_t pgrp); 00228 00229 /// Allows disabling of handle inheritance, default is TRUE. 00230 int handle_inheritance (void); 00231 void handle_inheritance (int); 00232 00233 /// Cause the specified handle to be passed to a child process 00234 /// when it runs a new program image. 00235 /** 00236 * The specified handle value will be included in the spawned 00237 * process's command line as @arg +H @arg handle, if a new 00238 * program is spawned (always on Win32; else if NO_EXEC is not 00239 * set in creation flags). The passed handle value will be 00240 * duplicated if on Win32 less capable than NT. 00241 * @return 0 if success, -1 if failure. 00242 */ 00243 int pass_handle (ACE_HANDLE); 00244 00245 /// Get a copy of the handles the ACE_Process_Options duplicated 00246 /// for the spawned process. 00247 /** 00248 * Any handles created through duplication of those passed into 00249 * @arg pass_handle are returned in @arg set. 00250 * @return 0 if there were no handles to return; 1 if there were. 00251 */ 00252 int dup_handles (ACE_Handle_Set &set) const; 00253 00254 /// Get a copy of the handles passed to the spawned process. This 00255 /// will be the set of handles previously passed to @arg pass_handle(). 00256 /** 00257 * Any handles previously passed to @arg pass_handle are returned 00258 * in @arg set. 00259 * @return 0 if there were no handles to return; 1 if there were. 00260 */ 00261 int passed_handles (ACE_Handle_Set &set) const; 00262 00263 /// Set value for avoid_zombies (has no real effect except on *nix). 00264 void avoid_zombies (int); 00265 00266 /// Get current value for avoid_zombies. 00267 int avoid_zombies (void); 00268 00269 /// Enable the use of a Unicode environment. This only makes sense 00270 /// for Win32 when ACE_USES_WCHAR is not defined. 00271 void enable_unicode_environment (void); 00272 00273 /// Disable the use of a Unicode environment. 00274 void disable_unicode_environment (void); 00275 00276 /// Return the unicode environment status 00277 bool use_unicode_environment (void) const; 00278 00279 #if defined (ACE_WIN32) 00280 // = Non-portable accessors for when you "just have to use them." 00281 00282 /// Used for setting and getting. 00283 ACE_TEXT_STARTUPINFO *startup_info (void); 00284 00285 /// Get the process_attributes. Returns NULL if 00286 /// set_process_attributes has not been set. 00287 LPSECURITY_ATTRIBUTES get_process_attributes (void) const; 00288 00289 /// If this is called, a non-null process attributes is sent to 00290 /// CreateProcess. 00291 LPSECURITY_ATTRIBUTES set_process_attributes (void); 00292 00293 /// Get the thread_attributes. Returns NULL if set_thread_attributes 00294 /// has not been set. 00295 LPSECURITY_ATTRIBUTES get_thread_attributes (void) const; 00296 00297 /// If this is called, a non-null thread attributes is sent to 00298 /// CreateProcess. 00299 LPSECURITY_ATTRIBUTES set_thread_attributes (void); 00300 00301 #else /* All things not WIN32 */ 00302 00303 /// argv-style array of environment settings. 00304 ACE_TCHAR *const *env_argv (void); 00305 00306 // = Accessors for the standard handles. 00307 ACE_HANDLE get_stdin (void) const; 00308 ACE_HANDLE get_stdout (void) const; 00309 ACE_HANDLE get_stderr (void) const; 00310 00311 // = Set/get real & effective user & group id associated with user. 00312 int setreugid (const ACE_TCHAR* user); 00313 void setruid (uid_t id); 00314 void seteuid (uid_t id); 00315 void setrgid (uid_t id); 00316 void setegid (uid_t id); 00317 uid_t getruid (void) const; 00318 uid_t geteuid (void) const; 00319 uid_t getrgid (void) const; 00320 uid_t getegid (void) const; 00321 00322 /** 00323 * Get the inherit_environment flag. 00324 */ 00325 bool inherit_environment (void) const; 00326 00327 /** 00328 * Set the inherit_environment flag. 00329 */ 00330 void inherit_environment (bool nv); 00331 #endif /* ACE_WIN32 */ 00332 protected: 00333 00334 #if !defined (ACE_HAS_WINCE) 00335 /// Add @a assignment to environment_buf_ and adjust 00336 /// environment_argv_. @a len is the strlen of @a assignment. 00337 int setenv_i (ACE_TCHAR *assignment, size_t len); 00338 00339 /// Whether the child process inherits the current process 00340 /// environment. 00341 bool inherit_environment_; 00342 #endif /* !ACE_HAS_WINCE */ 00343 00344 /// Default 0. 00345 u_long creation_flags_; 00346 00347 /// Avoid zombies for spawned processes. 00348 int avoid_zombies_; 00349 00350 #if defined (ACE_WIN32) && !defined (ACE_HAS_WINCE) 00351 /// Helper function to grab win32 environment and stick it in 00352 /// environment_buf_ using this->setenv_i. 00353 void inherit_environment (void); 00354 00355 /// Ensures once only call to inherit environment. 00356 int environment_inherited_; 00357 00358 ACE_TEXT_STARTUPINFO startup_info_; 00359 00360 /// Pointer to security_buf1_. 00361 LPSECURITY_ATTRIBUTES process_attributes_; 00362 00363 /// Pointer to security_buf2_. 00364 LPSECURITY_ATTRIBUTES thread_attributes_; 00365 00366 /// Data for process_attributes_. 00367 SECURITY_ATTRIBUTES security_buf1_; 00368 00369 /// Data for thread_attributes_. 00370 SECURITY_ATTRIBUTES security_buf2_; 00371 00372 #else /* !ACE_WIN32 */ 00373 ACE_HANDLE stdin_; 00374 ACE_HANDLE stdout_; 00375 ACE_HANDLE stderr_; 00376 00377 // = Real & effective user & group id's. 00378 // These should be set to -1 to leave unchanged (default). 00379 uid_t ruid_; 00380 uid_t euid_; 00381 uid_t rgid_; 00382 uid_t egid_; 00383 #endif /* ACE_WIN32 */ 00384 00385 /// Default true. 00386 bool handle_inheritance_; 00387 00388 #if !defined (ACE_HAS_WINCE) 00389 /// Is 1 if stdhandles was called. 00390 int set_handles_called_; 00391 00392 /// Pointer into environment_buf_. This should point to the next 00393 /// free spot. 00394 size_t environment_buf_index_; 00395 00396 /// Pointer to environment_argv_. 00397 size_t environment_argv_index_; 00398 00399 /// Pointer to buffer of the environment settings. 00400 ACE_TCHAR *environment_buf_; 00401 00402 /// Size of the environment buffer. Configurable 00403 size_t environment_buf_len_; 00404 00405 /// Pointers into environment_buf_. 00406 ACE_TCHAR **environment_argv_; 00407 00408 /// Maximum number of environment variables. Configurable 00409 size_t max_environment_args_; 00410 00411 /// Maximum index of environment_argv_ buffer 00412 size_t max_environ_argv_index_; 00413 00414 /// The current working directory. 00415 ACE_TCHAR working_directory_[MAXPATHLEN + 1]; 00416 #endif /* !ACE_HAS_WINCE */ 00417 00418 /// Ensures command_line_argv is only calculated once. 00419 bool command_line_argv_calculated_; 00420 00421 /// Pointer to buffer of command-line arguments. E.g., "-f foo -b bar". 00422 ACE_TCHAR *command_line_buf_; 00423 00424 /// Pointer to copy of command-line arguments, which is needed when 00425 /// converting a command-line string into a command-line argv. 00426 ACE_TCHAR *command_line_copy_; 00427 00428 /// Max length of command_line_buf_ 00429 size_t command_line_buf_len_; 00430 00431 /// Argv-style command-line arguments. 00432 ACE_TCHAR *command_line_argv_[MAX_COMMAND_LINE_OPTIONS]; 00433 00434 /// Process-group on Unix; unused on Win32. 00435 pid_t process_group_; 00436 00437 /// Set of handles that were passed in pass_handle (). 00438 ACE_Handle_Set handles_passed_; 00439 00440 /// Results of duplicating handles passed in pass_handle (). 00441 ACE_Handle_Set dup_handles_; 00442 00443 /// Pathname for the process. Relative path or absolute path or just 00444 /// the program name. 00445 ACE_TCHAR process_name_[MAXPATHLEN + 1]; 00446 00447 /// Indicate if a Unicode environment should be used 00448 bool use_unicode_environment_; 00449 }; 00450 00451 //class ACE_Process_Manager; 00452 00453 /** 00454 * @class ACE_Process 00455 * 00456 * @brief Process 00457 * 00458 * A Portable encapsulation for creating new processes. 00459 * Notice that on UNIX platforms, if the <setenv> is used, the 00460 * <spawn> is using the <execve> system call. It means that the 00461 * <command_line> should include a full path to the program file 00462 * (<execve> does not search the PATH). If <setenv> is not used 00463 * then, the <spawn> is using the <execvp> which searches for the 00464 * program file in the PATH variable. 00465 */ 00466 class ACE_Export ACE_Process 00467 { 00468 public: 00469 friend class ACE_Process_Manager; 00470 00471 /// Default construction. Must use <ACE_Process::spawn> to start. 00472 ACE_Process (void); 00473 00474 /// Destructor. 00475 virtual ~ACE_Process (void); 00476 00477 /** 00478 * Called just before <ACE_OS::fork> in the <spawn>. If this 00479 * returns non-zero, the <spawn> is aborted (and returns 00480 * ACE_INVALID_PID). The default simply returns zero. 00481 */ 00482 virtual int prepare (ACE_Process_Options &options); 00483 00484 /** 00485 * Launch a new process as described by @a options. On success, 00486 * returns 1 if the option avoid_zombies is set, else returns the 00487 * process id of the newly spawned child. Returns -1 on 00488 * failure. This will be fixed in the future versions of ACE when 00489 * the process id of the child will be returned regardless of the option. 00490 */ 00491 virtual pid_t spawn (ACE_Process_Options &options); 00492 00493 /// Called just after <ACE_OS::fork> in the parent's context, if the 00494 /// <fork> succeeds. The default is to do nothing. 00495 virtual void parent (pid_t child); 00496 00497 /** 00498 * Called just after <ACE_OS::fork> in the child's context. The 00499 * default does nothing. This function is *not* called on Win32 00500 * because the process-creation scheme does not allow it. 00501 */ 00502 virtual void child (pid_t parent); 00503 00504 /// Called by a Process_Manager that is removing this Process from 00505 /// its table of managed Processes. Default is to do nothing. 00506 virtual void unmanage (void); 00507 00508 /** 00509 * Wait for the process we've created to exit. If @a status != 0, it 00510 * points to an integer where the function store the exit status of 00511 * child process to. If @a wait_options == @c WNOHANG then return 0 00512 * and don't block if the child process hasn't exited yet. A return 00513 * value of -1 represents the <wait> operation failed, otherwise, 00514 * the child process id is returned. 00515 */ 00516 pid_t wait (ACE_exitcode *status = 0, 00517 int wait_options = 0); 00518 00519 /** 00520 * Timed wait for the process we've created to exit. A return value 00521 * of -1 indicates that the something failed; 0 indicates that a 00522 * timeout occurred. Otherwise, the child's process id is returned. 00523 * If @a status != 0, it points to an integer where the function 00524 * stores the child's exit status. 00525 * 00526 * @note On UNIX platforms this function uses <ualarm>, i.e., it 00527 * overwrites any existing alarm. In addition, it steals all 00528 * <SIGCHLD>s during the timeout period, which will break another 00529 * <ACE_Process_Manager> in the same process that's expecting 00530 * <SIGCHLD> to kick off process reaping. 00531 */ 00532 pid_t wait (const ACE_Time_Value &tv, 00533 ACE_exitcode *status = 0); 00534 00535 /// Send the process a signal. This is only portable to operating 00536 /// systems that support signals, such as UNIX/POSIX. 00537 int kill (int signum = SIGINT); 00538 00539 /** 00540 * Terminate the process abruptly using ACE::terminate_process(). 00541 * This call doesn't give the process a chance to cleanup, so use it 00542 * with caution... 00543 */ 00544 int terminate (void); 00545 00546 /// Return the process id of the new child process. 00547 pid_t getpid (void) const; 00548 00549 /// Return the handle of the process, if it has one. 00550 ACE_HANDLE gethandle (void) const; 00551 00552 /// Return 1 if running; 0 otherwise. 00553 int running (void) const; 00554 00555 /// Return the Process' exit code. This method returns the raw 00556 /// exit status returned from system APIs (such as <wait> or 00557 /// <waitpid>). This value is system dependent. 00558 ACE_exitcode exit_code (void) const; 00559 00560 /// Return the Process' return value. This method returns the 00561 /// actual return value that a child process returns or <exit>s. 00562 int return_value (void) const; 00563 00564 /// Close all the handles in the set obtained from the 00565 /// @arg ACE_Process_Options::dup_handles object used to spawn 00566 /// the process. 00567 void close_dup_handles (void); 00568 00569 /// Close all the handles in the set obtained from the 00570 /// @arg ACE_Process_Options::passed_handles object used to spawn 00571 /// the process. 00572 void close_passed_handles (void); 00573 00574 #if defined (ACE_WIN32) 00575 PROCESS_INFORMATION process_info (void); 00576 #endif /* ACE_WIN32 */ 00577 00578 private: 00579 00580 // Disallow copying and assignment since we don't support this (yet). 00581 ACE_Process (const ACE_Process &); 00582 void operator= (const ACE_Process &); 00583 00584 protected: 00585 /// Set this process' <exit_code_>. ACE_Process_Manager uses this 00586 /// method to set the <exit_code_> after successfully waiting for 00587 /// this process to exit. 00588 void exit_code (ACE_exitcode code); 00589 00590 #if defined (ACE_WIN32) 00591 PROCESS_INFORMATION process_info_; 00592 #else /* ACE_WIN32 */ 00593 /// Process id of the child. 00594 pid_t child_id_; 00595 #endif /* ACE_WIN32 */ 00596 ACE_exitcode exit_code_; 00597 00598 /// Set of handles that were passed to the child process. 00599 ACE_Handle_Set handles_passed_; 00600 00601 /// Handle duplicates made for the child process. 00602 ACE_Handle_Set dup_handles_; 00603 00604 private: 00605 #if defined (ACE_WIN32) && \ 00606 defined (ACE_HAS_WCHAR) && !defined (ACE_USES_WCHAR) && \ 00607 !defined (ACE_HAS_WINCE) 00608 wchar_t* convert_env_buffer (const char* env) const; 00609 #endif 00610 }; 00611 00612 /** 00613 * @class ACE_Managed_Process 00614 * 00615 * @brief A process easily managed by ACE_Process_Manager. 00616 * 00617 * @arg ACE_Managed_Process is just an @arg ACE_Process with an 00618 * @arg unmanage() method that deletes the instance. 00619 * This class is only valid for use as a dynamically-allocated object! 00620 */ 00621 class ACE_Export ACE_Managed_Process : public ACE_Process 00622 { 00623 public: 00624 00625 /// Cleanup by deleting @c this. 00626 virtual void unmanage (void); 00627 00628 protected: 00629 00630 /// Make sure that we're allocated dynamically! 00631 virtual ~ACE_Managed_Process (void); 00632 }; 00633 00634 ACE_END_VERSIONED_NAMESPACE_DECL 00635 00636 #if defined (__ACE_INLINE__) 00637 #include "ace/Process.inl" 00638 #endif /* __ACE_INLINE__ */ 00639 00640 #include /**/ "ace/post.h" 00641 #endif /* ACE_PROCESS_H */