---

ACE_Process Class Reference

Process. More...

#include <Process.h>

Inheritance diagram for ACE_Process:

[legend]Collaboration diagram for ACE_Process:

[legend]List of all members.

Public Methods
	ACE_Process (void)
	Default construction. Must use <ACE_Process::spawn> to start. More...
virtual	~ACE_Process (void)
	Destructor. More...
virtual int	prepare (ACE_Process_Options &options)
virtual pid_t	spawn (ACE_Process_Options &options)
virtual void	parent (pid_t child)
	Called just after <ACE_OS::fork> in the parent's context, if the <fork> succeeds. The default is to do nothing. More...
virtual void	child (pid_t parent)
virtual void	unmanage (void)
	Called by a <Process_Manager> that is removing this Process from its table of managed Processes. Default is to do nothing. More...
pid_t	wait (ACE_exitcode *status=0, int wait_options=0)
pid_t	wait (const ACE_Time_Value &tv, ACE_exitcode *status=0)
int	kill (int signum=SIGINT)
	Send the process a signal. This is only portable to operating systems that support signals, such as UNIX/POSIX. More...
int	terminate (void)
pid_t	getpid (void) const
	Return the process id of the new child process. More...
ACE_HANDLE	gethandle (void) const
	Return the handle of the process, if it has one. More...
int	running (void) const
	Return 1 if running; 0 otherwise. More...
ACE_exitcode	exit_code (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. More...
int	return_value (void) const
	Return the Process' return value. This method returns the actual return value that a child process returns or <exit>s. More...
void	close_dup_handles (void)
	Close all the handles in the set obtained from the ACE_Process_Options::dup_handles object used to spawn the process. More...
void	close_passed_handles (void)
	Close all the handles in the set obtained from the ACE_Process_Options::passed_handles object used to spawn the process. More...
PROCESS_INFORMATION	process_info (void)
Protected Methods
void	exit_code (ACE_exitcode code)
	Set this process' <exit_code_>. ACE_Process_Manager uses this method to set the <exit_code_> after successfully waiting for this proecess to exit. More...
Protected Attributes
PROCESS_INFORMATION	process_info_
ACE_exitcode	exit_code_
ACE_Handle_Set	handles_passed_
	Set of handles that were passed to the child process. More...
ACE_Handle_Set	dup_handles_
	Handle duplicates made for the child process. More...
Friends
class	ACE_Process_Manager

---

Detailed Description

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.

Definition at line 430 of file Process.h.

---

Constructor & Destructor Documentation

ACE_Process::ACE_Process (  void    )

Default construction. Must use <ACE_Process::spawn> to start. Definition at line 31 of file Process.cpp. References ACE_INVALID_PID, and ACE_OS_String::memset. : #if !defined (ACE_WIN32) child_id_ (ACE_INVALID_PID), #endif /* !defined (ACE_WIN32) */ exit_code_ (0) { #if defined (ACE_WIN32) ACE_OS::memset ((void *) &this->process_info_, 0, sizeof this->process_info_); #endif /* ACE_WIN32 */ }

ACE_Process::~ACE_Process (  void    )  [virtual]

Destructor. Definition at line 45 of file Process.cpp. References ACE_OS::close, and close_dup_handles. { #if defined (ACE_WIN32) // Free resources allocated in kernel. ACE_OS::close (this->process_info_.hThread); ACE_OS::close (this->process_info_.hProcess); #endif /* ACE_WIN32 */ // If any handles were duplicated for the child process and // still not closed, get them now. this->close_dup_handles (); }

---

Member Function Documentation

void ACE_Process::child (  pid_t    parent )  [virtual]

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. Definition at line 329 of file Process.cpp. References pid_t. Referenced by spawn. { // nothing to do }

void ACE_Process::close_dup_handles (  void    )

Close all the handles in the set obtained from the ACE_Process_Options::dup_handles object used to spawn the process. Definition at line 440 of file Process.cpp. References ACE_OS::closesocket, dup_handles_, ACE_Handle_Set::num_set, and ACE_Handle_Set::reset. Referenced by ~ACE_Process. { if (this->dup_handles_.num_set () > 0) { ACE_Handle_Set_Iterator h_iter (this->dup_handles_); for (ACE_HANDLE h = h_iter (); h != ACE_INVALID_HANDLE; h = h_iter ()) ACE_OS::closesocket (h); this->dup_handles_.reset (); } return; }

void ACE_Process::close_passed_handles (  void    )

Close all the handles in the set obtained from the ACE_Process_Options::passed_handles object used to spawn the process. Definition at line 455 of file Process.cpp. References ACE_OS::closesocket, handles_passed_, ACE_Handle_Set::num_set, and ACE_Handle_Set::reset. { if (this->handles_passed_.num_set () > 0) { ACE_Handle_Set_Iterator h_iter (this->handles_passed_); for (ACE_HANDLE h = h_iter (); h != ACE_INVALID_HANDLE; h = h_iter ()) ACE_OS::closesocket (h); this->handles_passed_.reset (); } return; }

ACE_INLINE void ACE_Process::exit_code (  ACE_exitcode    code )  [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. Definition at line 87 of file Process.i. References ACE_exitcode, and exit_code_. { this->exit_code_ = code; }

ACE_INLINE ACE_exitcode ACE_Process::exit_code (  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. Definition at line 81 of file Process.i. References exit_code_. Referenced by ACE_Process_Manager::notify_proc_handler. { return this->exit_code_; }

ACE_INLINE ACE_HANDLE ACE_Process::gethandle (  void    )  const

Return the handle of the process, if it has one. Definition at line 14 of file Process.i. References process_info_. Referenced by ACE_Process_Manager::append_proc, ACE_Process_Manager::find_proc, ACE_Process_Manager::remove_proc, running, and ACE_Process_Manager::wait. { #if defined (ACE_WIN32) return process_info_.hProcess; #else return ACE_HANDLE (child_id_); #endif /* ACE_WIN32 */ }

ACE_INLINE pid_t ACE_Process::getpid (  void    )  const

Return the process id of the new child process. Definition at line 24 of file Process.i. Referenced by ACE_Process_Manager::find_proc, ACE_Process_Manager::handle_signal, ACE_Process_Manager::insert_proc, kill, spawn, terminate, ACE_Process_Manager::wait, and wait. { #if defined (ACE_WIN32) return process_info_.dwProcessId; #else /* ACE_WIN32 */ return child_id_; #endif /* ACE_WIN32 */ }

ACE_INLINE int ACE_Process::kill (  int    signum = SIGINT )

Send the process a signal. This is only portable to operating systems that support signals, such as UNIX/POSIX. Definition at line 53 of file Process.i. References getpid, and ACE_OS::kill. { if (this->getpid () != -1) return ACE_OS::kill (this->getpid (), signum); else return -1; }

void ACE_Process::parent (  pid_t    child )  [virtual]

Called just after <ACE_OS::fork> in the parent's context, if the <fork> succeeds. The default is to do nothing. Definition at line 323 of file Process.cpp. References pid_t. Referenced by spawn. { // nothing to do }

int ACE_Process::prepare (  ACE_Process_Options &    options )  [virtual]

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. Definition at line 58 of file Process.cpp. Referenced by spawn. { return 0; }

PROCESS_INFORMATION ACE_Process::process_info (  void    )

ACE_INLINE int ACE_Process::return_value (  void    )  const

Return the Process' return value. This method returns the actual return value that a child process returns or <exit>s. Definition at line 71 of file Process.i. References exit_code_, and WEXITSTATUS. { #if defined (ACE_WIN32) return this->exit_code_; #else return WEXITSTATUS (this->exit_code_); #endif /* ACE_WIN32 */ }

int ACE_Process::running (  void    )  const

Return 1 if running; 0 otherwise. Definition at line 341 of file Process.cpp. References gethandle, and ACE_OS::kill. { #if defined (ACE_WIN32) DWORD code; BOOL result = ::GetExitCodeProcess (this->gethandle (), &code); return result && code == STILL_ACTIVE; #else return ACE_OS::kill (this->getpid (), 0) == 0 || errno != ESRCH; #endif /* ACE_WIN32 */ }

pid_t ACE_Process::spawn (  ACE_Process_Options &    options )  [virtual]

Launch a new process as described by <options>. Returns the process id of the newly spawned child on success or -1 on failure. Definition at line 64 of file Process.cpp. References ACE_OS::_exit, ACE_BIT_ENABLED, ACE_ERROR, ACE_INVALID_PID, ACE_LIB_TEXT, ACE_STDERR, ACE_STDIN, ACE_STDOUT, ACE_TCHAR, ACE_Process_Options::avoid_zombies, ACE_OS::chdir, child, ACE_OS::close, ACE_Process_Options::command_line_argv, ACE_Process_Options::command_line_buf, ACE_Process_Options::creation_flags, ACE_OS::dup2, ACE_Process_Options::dup_handles, dup_handles_, ACE_Process_Options::env_buf, ACE_OS::execve, ACE_OS::execvp, ACE_OS::exit, ACE::fork, ACE_Process_Options::get_process_attributes, ACE_Process_Options::get_thread_attributes, ACE_Process_Options::getgroup, getpid, ACE_OS::getppid, ACE_Process_Options::handle_inheritence, handles_passed_, ACE_Process_Options::inherit_environment, LM_ERROR, ACE_Process_Options::NO_EXEC, parent, ACE_Process_Options::passed_handles, prepare, process_info_, ACE_Process_Options::process_name, ACE_OS::putenv, ACE_OS::setpgid, ACE_OS::setregid, ACE_OS::setreuid, ACE_OS::sprintf, ACE_Process_Options::startup_info, ACE_OS_String::strlen, and ACE_Process_Options::working_directory. Referenced by ACE_Process_Manager::spawn. { if (prepare (options) < 0) return ACE_INVALID_PID; // Stash the passed/duped handle sets away in this object for later // closing if needed or requested. At the same time, figure out which // ones to include in command line options if that's needed below. ACE_Handle_Set *set_p = 0; if (options.dup_handles (this->dup_handles_)) set_p = &this->dup_handles_; else if (options.passed_handles (this->handles_passed_)) set_p = &this->handles_passed_; // If we are going to end up running a new program (i.e. Win32, or // NO_EXEC option is set) then get any handles passed in the options, // and tack them onto the command line with +H <handle> options, // unless the command line runs out of space. // Note that we're using the knowledge that all the options, argvs, etc. // passed to the options are all sitting in the command_line_buf. Any // call to get the argv then splits them out. So, regardless of the // platform, tack them all onto the command line buf and take it // from there. if (set_p && !ACE_BIT_ENABLED (options.creation_flags (), ACE_Process_Options::NO_EXEC)) { int maxlen = 0; ACE_TCHAR *cmd_line_buf = options.command_line_buf (&maxlen); size_t max_len = ACE_static_cast (size_t, maxlen); size_t curr_len = ACE_OS::strlen (cmd_line_buf); ACE_Handle_Set_Iterator h_iter (*set_p); // Because the length of the to-be-formatted +H option is not // known, and we don't have a snprintf, guess at the space // needed (20 chars), and use that as a limit. for (ACE_HANDLE h = h_iter (); h != ACE_INVALID_HANDLE && curr_len + 20 < max_len; h = h_iter ()) { curr_len += ACE_OS::sprintf (&cmd_line_buf[curr_len], ACE_LIB_TEXT (" +H %d"), h); } } #if defined (ACE_HAS_WINCE) // Note that WinCE does not have process name included in the command line as argv[0] // like other OS environment. Therefore, it is user's whole responsibility to call // 'ACE_Process_Options::process_name(const ACE_TCHAR *name)' to set the proper // process name (the execution file name with path if needed). BOOL fork_result = ACE_TEXT_CreateProcess (options.process_name(), options.command_line_buf(), options.get_process_attributes(), // must be NULL in CE options.get_thread_attributes(), // must be NULL in CE options.handle_inheritence(), // must be false in CE options.creation_flags(), // must be NULL in CE options.env_buf(), // environment variables, must be NULL in CE options.working_directory(), // must be NULL in CE options.startup_info(), // must be NULL in CE &this->process_info_); if (fork_result) { parent (this->getpid ()); return this->getpid (); } return ACE_INVALID_PID; #elif defined (ACE_WIN32) BOOL fork_result = ACE_TEXT_CreateProcess (0, options.command_line_buf (), options.get_process_attributes (), options.get_thread_attributes (), options.handle_inheritence (), options.creation_flags (), options.env_buf (), // environment variables options.working_directory (), options.startup_info (), &this->process_info_); if (fork_result) { parent (this->getpid ()); return this->getpid (); } return ACE_INVALID_PID; #elif defined (CHORUS) // This only works if we exec. Chorus does not really support // forking. if (ACE_BIT_ENABLED (options.creation_flags (), ACE_Process_Options::NO_EXEC)) ACE_NOTSUP_RETURN (ACE_INVALID_PID); // These are all currently unsupported. if (options.get_stdin () != ACE_INVALID_HANDLE) ACE_NOTSUP_RETURN (ACE_INVALID_PID); if (options.get_stdout () != ACE_INVALID_HANDLE) ACE_NOTSUP_RETURN (ACE_INVALID_PID); if (options.get_stderr () != ACE_INVALID_HANDLE) ACE_NOTSUP_RETURN (ACE_INVALID_PID); if (options.working_directory () != 0) ACE_NOTSUP_RETURN (ACE_INVALID_PID); if (options.env_argv ()[0] == 0) // command-line args this->child_id_ = ACE_OS::execvp (options.process_name (), options.command_line_argv ()); else { // Add the new environment variables to the environment context // of the context before doing an <execvp>. for (char *const *user_env = options.env_argv (); *user_env != 0; user_env++) if (ACE_OS::putenv (*user_env) != 0) return ACE_INVALID_PID; // Now the forked process has both inherited variables and the // user's supplied variables. this->child_id_ = ACE_OS::execvp (options.process_name (), options.command_line_argv ()); } return this->child_id_; #else /* ACE_WIN32 */ // Fork the new process. this->child_id_ = ACE::fork (options.process_name (), options.avoid_zombies ()); if (this->child_id_ == 0) { # if !defined (ACE_LACKS_SETPGID) // If we're the child and the options specified a non-default // process group, try to set our pgid to it. This allows the // <ACE_Process_Manager> to wait for processes by their // process-group. if (options.getgroup () != ACE_INVALID_PID && ACE_OS::setpgid (0, options.getgroup ()) < 0) ACE_ERROR ((LM_ERROR, ACE_LIB_TEXT ("%p.\n"), ACE_LIB_TEXT ("ACE_Process::spawn: setpgid failed."))); # endif /* ACE_LACKS_SETPGID */ # if !defined (ACE_LACKS_SETREGID) if (options.getrgid () != (uid_t) -1 || options.getegid () != (uid_t) -1) if (ACE_OS::setregid (options.getrgid (), options.getegid ()) == -1) ACE_ERROR ((LM_ERROR, ACE_LIB_TEXT ("%p.\n"), ACE_LIB_TEXT ("ACE_Process::spawn: setregid failed."))); # endif /* ACE_LACKS_SETREGID */ # if !defined (ACE_LACKS_SETREUID) // Set user and group id's. if (options.getruid () != (uid_t) -1 || options.geteuid () != (uid_t) -1) if (ACE_OS::setreuid (options.getruid (), options.geteuid ()) == -1) ACE_ERROR ((LM_ERROR, ACE_LIB_TEXT ("%p.\n"), ACE_LIB_TEXT ("ACE_Process::spawn: setreuid failed."))); # endif /* ACE_LACKS_SETREUID */ this->child (ACE_OS::getppid ()); } else if (this->child_id_ != -1) this->parent (this->child_id_); // If we're not supposed to exec, return the process id. if (ACE_BIT_ENABLED (options.creation_flags (), ACE_Process_Options::NO_EXEC)) return this->child_id_; switch (this->child_id_) { case -1: // Error. return ACE_INVALID_PID; case 0: // Child process...exec the { if (options.get_stdin () != ACE_INVALID_HANDLE && ACE_OS::dup2 (options.get_stdin (), ACE_STDIN) == -1) ACE_OS::exit (errno); else if (options.get_stdout () != ACE_INVALID_HANDLE && ACE_OS::dup2 (options.get_stdout (), ACE_STDOUT) == -1) ACE_OS::exit (errno); else if (options.get_stderr () != ACE_INVALID_HANDLE && ACE_OS::dup2 (options.get_stderr (), ACE_STDERR) == -1) ACE_OS::exit (errno); // close down unneeded descriptors ACE_OS::close (options.get_stdin ()); ACE_OS::close (options.get_stdout ()); ACE_OS::close (options.get_stderr ()); // If we must, set the working directory for the child // process. if (options.working_directory () != 0) ACE_OS::chdir (options.working_directory ()); // Should check for error here! // Child process executes the command. int result = 0; if (options.inherit_environment ()) { // Add the new environment variables to the environment // context of the context before doing an <execvp>. for (char *const *user_env = options.env_argv (); *user_env != 0; user_env++) if (ACE_OS::putenv (*user_env) != 0) return ACE_INVALID_PID; // Now the forked process has both inherited variables and // the user's supplied variables. result = ACE_OS::execvp (options.process_name (), options.command_line_argv ()); } else { #if defined (ghs) // GreenHills 1.8.8 (for VxWorks 5.3.x) can't compile this // code. Processes aren't supported on VxWorks anyways. ACE_NOTSUP_RETURN (ACE_INVALID_PID); #else result = ACE_OS::execve (options.process_name (), options.command_line_argv (), options.env_argv ()); # endif /* ghs */ } if (result == -1) { // If the execv fails, this child needs to exit. // Exit with the errno so that the calling process can // catch this and figure out what went wrong. ACE_OS::_exit (errno); } // ... otherwise, this is never reached. return 0; } default: // Server process. The fork succeeded. return this->child_id_; } #endif /* ACE_WIN32 */ }

ACE_INLINE int ACE_Process::terminate (  void    )

Terminate the process abruptly using <ACE::terminate_process>. This call doesn't give the process a chance to cleanup, so use it with caution... Definition at line 62 of file Process.i. References getpid, and ACE::terminate_process. { if (this->getpid () != -1) return ACE::terminate_process (this->getpid ()); else return -1; }

void ACE_Process::unmanage (  void    )  [virtual]

Called by a <Process_Manager> that is removing this Process from its table of managed Processes. Default is to do nothing. Reimplemented in ACE_Managed_Process. Definition at line 335 of file Process.cpp. Referenced by ACE_Process_Manager::remove_proc. { // nothing to do }

pid_t ACE_Process::wait (  const ACE_Time_Value &    tv, ACE_exitcode *    status = 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. Definition at line 357 of file Process.cpp. References ACE_exitcode, ACE_INVALID_PID, ACE_SignalHandler, ETIME, exit_code_, getpid, ACE_Time_Value::max_time, ACE_Time_Value::msec, pid_t, process_info_, ACE_Sig_Action::register_action, ACE_OS::set_errno_to_last_error, SIGCHLD, ACE_OS::sleep, ACE_Countdown_Time::update, wait, ACE_OS::waitpid, WNOHANG, and ACE_Time_Value::zero. { #if defined (ACE_WIN32) // Don't try to get the process exit status if wait failed so we can // keep the original error code intact. switch (::WaitForSingleObject (process_info_.hProcess, tv.msec ())) { case WAIT_OBJECT_0: // The error status of <GetExitCodeProcess> is nonetheless not // tested because we don't know how to return the value. ::GetExitCodeProcess (process_info_.hProcess, &this->exit_code_); if (status != 0) *status = this->exit_code_; return this->getpid (); case WAIT_TIMEOUT: errno = ETIME; return 0; default: ACE_OS::set_errno_to_last_error (); return -1; } #else /* ACE_WIN32 */ if (tv == ACE_Time_Value::zero) { pid_t retv = ACE_OS::waitpid (this->child_id_, &this->exit_code_, WNOHANG); if (status != 0) *status = this->exit_code_; return retv; } if (tv == ACE_Time_Value::max_time) return this->wait (status); // Need to wait but limited to specified time. // Force generation of SIGCHLD, even though we don't want to // catch it - just need it to interrupt the sleep below. // If this object has a reactor set, assume it was given at // open(), and there's already a SIGCHLD action set, so no // action is needed here. ACE_Sig_Action old_action; ACE_Sig_Action do_sigchld ((ACE_SignalHandler)sigchld_nop); do_sigchld.register_action (SIGCHLD, &old_action); pid_t pid; ACE_Time_Value tmo (tv); // Need one we can change for (ACE_Countdown_Time time_left (&tmo); ; time_left.update ()) { pid = ACE_OS::waitpid (this->getpid (), &this->exit_code_, WNOHANG); if (status != 0) *status = this->exit_code_; if (pid > 0 || pid == ACE_INVALID_PID) break; // Got a child or an error - all done // pid 0, nothing is ready yet, so wait. // Do a sleep (only this thread sleeps) til something // happens. This relies on SIGCHLD interrupting the sleep. // If SIGCHLD isn't delivered, we'll need to do something // with sigaction to force it. if (-1 == ACE_OS::sleep (tmo) && errno == EINTR) continue; // Timed out pid = 0; break; } // Restore the previous SIGCHLD action if it was changed. old_action.register_action (SIGCHLD); return pid; #endif /* ACE_WIN32 */ }

ACE_INLINE pid_t ACE_Process::wait (  ACE_exitcode *    status = 0, int    wait_options = 0 )

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. Definition at line 35 of file Process.i. References ACE_exitcode, exit_code_, pid_t, process_info_, and ACE_OS::wait. Referenced by ACE_Process_Manager::wait, and wait. { pid_t retv = ACE_OS::wait (this->getpid (), &this->exit_code_, wait_options #if defined (ACE_WIN32) , process_info_.hProcess #endif /* ACE_WIN32 */ ); if (status != 0) *status = this->exit_code_; return retv; }

---

Friends And Related Function Documentation

friend class ACE_Process_Manager [friend]

Definition at line 433 of file Process.h.

---

Member Data Documentation

ACE_Handle_Set ACE_Process::dup_handles_ [protected]

Handle duplicates made for the child process. Definition at line 557 of file Process.h. Referenced by close_dup_handles, and spawn.

ACE_exitcode ACE_Process::exit_code_ [protected]

Definition at line 552 of file Process.h. Referenced by exit_code, return_value, and wait.

ACE_Handle_Set ACE_Process::handles_passed_ [protected]

Set of handles that were passed to the child process. Definition at line 555 of file Process.h. Referenced by close_passed_handles, and spawn.

PROCESS_INFORMATION ACE_Process::process_info_ [protected]

Definition at line 547 of file Process.h. Referenced by gethandle, spawn, and wait.

---

The documentation for this class was generated from the following files:

• Process.h
• Process.cpp
• Process.i

---