Main Page Class Hierarchy Alphabetical List Compound List File List Compound Members File Members Related Pages

# ACE_Process_Options Class Reference

Process Options. More...

`#include <Process.h>`

Collaboration diagram for ACE_Process_Options:

[legend]
List of all members.

## Public Types
enum | { DEFAULT_COMMAND_LINE_BUF_LEN = 1024, NO_EXEC = 0 }
## Public Methods
| 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)
| If <inherit_environment> == 1, the new process will inherit the environment of the current process. More...
| ~ACE_Process_Options (void)
| Destructor. More...
int | set_handles (ACE_HANDLE std_in, ACE_HANDLE std_out=ACE_INVALID_HANDLE, ACE_HANDLE std_err=ACE_INVALID_HANDLE)
| Set the standard handles of the new process to the respective handles. More...
void | release_handles (void)
| Felease the standard handles previously set with set_handles;. More...
int | setenv (const ACE_TCHAR *format,...)
| <format> must be of the form "VARIABLE=VALUE". There can not be any spaces between VARIABLE and the equal sign. More...
int | setenv (const ACE_TCHAR *variable_name, const ACE_TCHAR *format,...)
| Set a single environment variable, <variable_name>. More...
int | setenv (ACE_TCHAR *envp[])
| Same as above with argv format. <envp> must be null terminated. More...
void | working_directory (const char *wd)
| Set the working directory for the process. strlen of <wd> must be <= MAXPATHLEN. More...
void | working_directory (const wchar_t *wd)
| wchar_t version of working_directory. More...
int | command_line (const ACE_TCHAR *format,...)
| Set the command-line arguments. More...
int | command_line (const ACE_ANTI_TCHAR *format,...)
| Anti-TChar version of command_line (). More...
int | command_line (const ACE_TCHAR *const argv[])
| Same as above in argv format. <argv> must be null terminated. More...
void | process_name (const ACE_TCHAR *name)
| Specify the full path or relative path, or just the executable name for the process. More...
const ACE_TCHAR * | process_name (void)
| Return the process_name. If the <process_name(name)> set method is not called, this method will return argv[0]. More...
u_long | creation_flags (void) const
| Get the creation flags. More...
void | creation_flags (u_long)
| Set the creation flags. More...
ACE_TCHAR * | working_directory (void)
| Current working directory. Returns "" if nothing has been set. More...
ACE_TCHAR * | command_line_buf (int *max_len=0)
| 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. max_len, if non-zero, provides a location into which the total length of the command line buffer is returned. More...
ACE_TCHAR *const * | command_line_argv (void)
| argv-style command-line options. More...
ACE_TCHAR * | env_buf (void)
| Null-terminated buffer of null terminated strings. More...
pid_t | getgroup (void) const
| Get the process group. On UNIX, these methods are used by the <ACE_Process_Manager> to manage groups of processes. More...
pid_t | setgroup (pid_t pgrp)
| Set the process group. On UNIX, these methods are used by the <ACE_Process_Manager> to manage groups of processes. More...
int | handle_inheritence (void)
| Default is TRUE. Allows disabling of handle inheritence. More...
void | handle_inheritence (int)
int | pass_handle (ACE_HANDLE)
| The specified handle value will be included in the spawned process's command line as +H handle, if a new program is spawned (always on Win32; else if NO_EXEC is not set in creation flags). More...
int | dup_handles (ACE_Handle_Set &set) const
| Any handles created through duplication of those passed into pass_handle are returned in set. More...
int | passed_handles (ACE_Handle_Set &set) const
| Any handles previously passed to pass_handle are returned in set. More...
void | avoid_zombies (int)
| Set value for avoid_zombies (has no real effect except on *nix). More...
int | avoid_zombies (void)
| Get current value for avoid_zombies. More...
ACE_TEXT_STARTUPINFO * | startup_info (void)
| Used for setting and getting. More...
LPSECURITY_ATTRIBUTES | get_process_attributes (void) const
| Get the process_attributes. Returns NULL if set_process_attributes has not been set. More...
LPSECURITY_ATTRIBUTES | set_process_attributes (void)
| If this is called, a non-null process attributes is sent to CreateProcess. More...
LPSECURITY_ATTRIBUTES | get_thread_attributes (void) const
| Get the thread_attributes. Returns NULL if set_thread_attributes has not been set. More...
LPSECURITY_ATTRIBUTES | set_thread_attributes (void)
| If this is called, a non-null thread attributes is sent to CreateProcess. More...
## Protected Types
enum | { MAX_COMMAND_LINE_OPTIONS = 128, ENVIRONMENT_BUFFER = 16 * 1024, MAX_ENVIRONMENT_ARGS = 512 }
## Protected Methods
int | setenv_i (ACE_TCHAR *assignment, size_t len)
| Add <assignment> to environment_buf_ and adjust environment_argv_. <len> is the strlen of <assignment>. More...
void | inherit_environment (void)
| Helper function to grab win32 environment and stick it in environment_buf_ using this->setenv_i. More...
## Protected Attributes
int | inherit_environment_
| Whether the child process inherits the current process environment. More...
u_long | creation_flags_
| Default 0. More...
int | avoid_zombies_
| Avoid zombies for spawned processes. More...
int | environment_inherited_
| Ensures once only call to inherit environment. More...
ACE_TEXT_STARTUPINFO | startup_info_
BOOL | handle_inheritence_
| Default TRUE. More...
LPSECURITY_ATTRIBUTES | process_attributes_
| Pointer to security_buf1_. More...
LPSECURITY_ATTRIBUTES | thread_attributes_
| Pointer to security_buf2_. More...
SECURITY_ATTRIBUTES | security_buf1_
| Data for process_attributes_. More...
SECURITY_ATTRIBUTES | security_buf2_
| Data for thread_attributes_. More...
int | set_handles_called_
| Is 1 if stdhandles was called. More...
size_t | environment_buf_index_
| Pointer into environment_buf_. This should point to the next free spot. More...
int | environment_argv_index_
| Pointer to environment_argv_. More...
ACE_TCHAR * | environment_buf_
| Pointer to buffer of the environment settings. More...
size_t | environment_buf_len_
| Size of the environment buffer. Configurable. More...
ACE_TCHAR ** | environment_argv_
| Pointers into environment_buf_. More...
int | max_environment_args_
| Maximum number of environment variables. Configurable. More...
int | max_environ_argv_index_
| Maximum index of environment_argv_ buffer. More...
ACE_TCHAR | working_directory_ [MAXPATHLEN+1]
| The current working directory. More...
int | command_line_argv_calculated_
| Ensures command_line_argv is only calculated once. More...
ACE_TCHAR * | command_line_buf_
| Pointer to buffer of command-line arguments. E.g., "-f foo -b bar". More...
int | command_line_buf_len_
| Max length of command_line_buf_. More...
ACE_TCHAR * | command_line_argv_ [MAX_COMMAND_LINE_OPTIONS]
| Argv-style command-line arguments. More...
pid_t | process_group_
| Process-group on Unix; unused on Win32. More...
ACE_Handle_Set | handles_passed_
| Set of handles that were passed in pass_handle (). More...
ACE_Handle_Set | dup_handles_
| Results of duplicating handles passed in pass_handle (). More...
ACE_TCHAR | process_name_ [MAXPATHLEN+1]
| Pathname for the process. Relative path or absolute path or just the program name. More...

## Detailed Description

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.

## Member Enumeration Documentation

anonymous enum

  | Enumeration values:
  DEFAULT_COMMAND_LINE_BUF_LEN |
  NO_EXEC |

anonymous enum`[protected]`

  | Enumeration values:
  MAX_COMMAND_LINE_OPTIONS |
  ENVIRONMENT_BUFFER |
  MAX_ENVIRONMENT_ARGS |

## Constructor & Destructor Documentation

ACE_Process_Options::ACE_Process_Options | ( | int | ie = 1,
|  | int | cobl = DEFAULT_COMMAND_LINE_BUF_LEN,
|  | int | ebl = ENVIRONMENT_BUFFER,
|  | int | mea = MAX_ENVIRONMENT_ARGS
| ) |

| 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::~ACE_Process_Options | ( | void |  | ) |

| Destructor.

## Member Function Documentation

ACE_INLINE int ACE_Process_Options::avoid_zombies | ( | void |  | ) |

| Get current value for avoid_zombies.

ACE_INLINE void ACE_Process_Options::avoid_zombies | ( | int | avoid_zombies | ) |

| Set value for avoid_zombies (has no real effect except on *nix).

int ACE_Process_Options::command_line | ( | const ACE_TCHAR *const | argv[] | ) |

| Same as above in argv format. <argv> must be null terminated.

int ACE_Process_Options::command_line | ( | const ACE_ANTI_TCHAR * | format,
|  | ... |
| ) |

| Anti-TChar version of command_line (). Note: Not available on Windows CE because it doesn't have a char version of vsprintf.

int ACE_Process_Options::command_line | ( | const ACE_TCHAR * | format,
|  | ... |
| ) |

| 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.

ACE_TCHAR *const * ACE_Process_Options::command_line_argv | ( | void |  | ) |

| 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_INLINE ACE_TCHAR * ACE_Process_Options::command_line_buf | ( | int * | max_lenp = 0 | ) |

| 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. max_len, if non-zero, provides a location into which the total length of the command line buffer is returned.

ACE_INLINE void ACE_Process_Options::creation_flags | ( | u_long | cf | ) |

| Set the creation flags.

ACE_INLINE u_long ACE_Process_Options::creation_flags | ( | void |  | ) | const

| Get the creation flags.

int ACE_Process_Options::dup_handles | ( | ACE_Handle_Set & | set | ) | const

| Any handles created through duplication of those passed into pass_handle are returned in set. Returns: 0 if there were no handles to return; 1 if there were.

ACE_TCHAR * ACE_Process_Options::env_buf | ( | void |  | ) |

| Null-terminated buffer of null terminated strings. Each string is an environment assignment "VARIABLE=value". This buffer should end with two null characters.

LPSECURITY_ATTRIBUTES ACE_Process_Options::get_process_attributes | ( | void |  | ) | const

| Get the process_attributes. Returns NULL if set_process_attributes has not been set.

LPSECURITY_ATTRIBUTES ACE_Process_Options::get_thread_attributes | ( | void |  | ) | const

| Get the thread_attributes. Returns NULL if set_thread_attributes has not been set.

ACE_INLINE pid_t ACE_Process_Options::getgroup | ( | void |  | ) | const

| Get the process group. On UNIX, these methods are used by the <ACE_Process_Manager> to manage groups of processes.

ACE_INLINE void ACE_Process_Options::handle_inheritence | ( | int | hi | ) |

ACE_INLINE int ACE_Process_Options::handle_inheritence | ( | void |  | ) |

| Default is TRUE. Allows disabling of handle inheritence.

void ACE_Process_Options::inherit_environment | ( | void |  | ) | `[protected]`

| Helper function to grab win32 environment and stick it in environment_buf_ using this->setenv_i.

int ACE_Process_Options::pass_handle | ( | ACE_HANDLE | h | ) |

| The specified handle value will be included in the spawned process's command line as +H 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. Returns: 0 if success, -1 if failure.

int ACE_Process_Options::passed_handles | ( | ACE_Handle_Set & | set | ) | const

| Any handles previously passed to pass_handle are returned in set. Returns: 0 if there were no handles to return; 1 if there were.

ACE_INLINE const ACE_TCHAR * ACE_Process_Options::process_name | ( | void |  | ) |

| Return the process_name. If the <process_name(name)> set method is not called, this method will return argv[0].

ACE_INLINE void ACE_Process_Options::process_name | ( | const ACE_TCHAR * | p | ) |

| 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 ACE_Process_Options::release_handles | ( | void |  | ) |

| Felease the standard handles previously set with set_handles;.

int ACE_Process_Options::set_handles | ( | ACE_HANDLE | std_in,
|  | ACE_HANDLE | std_out = ACE_INVALID_HANDLE,
|  | ACE_HANDLE | std_err = ACE_INVALID_HANDLE
| ) |

| 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.

LPSECURITY_ATTRIBUTES ACE_Process_Options::set_process_attributes | ( | void |  | ) |

| If this is called, a non-null process attributes is sent to CreateProcess.

LPSECURITY_ATTRIBUTES ACE_Process_Options::set_thread_attributes | ( | void |  | ) |

| If this is called, a non-null thread attributes is sent to CreateProcess.

int ACE_Process_Options::setenv | ( | ACE_TCHAR * | envp[] | ) |

| Same as above with argv format. <envp> must be null terminated.

int ACE_Process_Options::setenv | ( | const ACE_TCHAR * | variable_name,
|  | 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 ACE_Process_Options::setenv | ( | const ACE_TCHAR * | format,
|  | ... |
| ) |

| <format> must be of the form "VARIABLE=VALUE". There can not be any spaces between VARIABLE and the equal sign.

int ACE_Process_Options::setenv_i | ( | ACE_TCHAR * | assignment,
|  | size_t | len
| ) | `[protected]`

| Add <assignment> to environment_buf_ and adjust environment_argv_. <len> is the strlen of <assignment>.

ACE_INLINE pid_t ACE_Process_Options::setgroup | ( | pid_t | pgrp | ) |

| Set the process group. On UNIX, these methods are used by the <ACE_Process_Manager> to manage groups of processes.

ACE_TEXT_STARTUPINFO* ACE_Process_Options::startup_info | ( | void |  | ) |

| Used for setting and getting.

ACE_INLINE ACE_TCHAR * ACE_Process_Options::working_directory | ( | void |  | ) |

| Current working directory. Returns "" if nothing has been set.

void ACE_Process_Options::working_directory | ( | const wchar_t * | wd | ) |

| wchar_t version of working_directory.

ACE_INLINE void ACE_Process_Options::working_directory | ( | const char * | wd | ) |

| Set the working directory for the process. strlen of <wd> must be <= MAXPATHLEN.

## Member Data Documentation

int ACE_Process_Options::avoid_zombies_`[protected]`

| Avoid zombies for spawned processes.

ACE_TCHAR* ACE_Process_Options::command_line_argv_[MAX_COMMAND_LINE_OPTIONS]`[protected]`

| Argv-style command-line arguments.

int ACE_Process_Options::command_line_argv_calculated_`[protected]`

| Ensures command_line_argv is only calculated once.

ACE_TCHAR* ACE_Process_Options::command_line_buf_`[protected]`

| Pointer to buffer of command-line arguments. E.g., "-f foo -b bar".

int ACE_Process_Options::command_line_buf_len_`[protected]`

| Max length of command_line_buf_.

u_long ACE_Process_Options::creation_flags_`[protected]`

| Default 0.

ACE_Handle_Set ACE_Process_Options::dup_handles_`[protected]`

| Results of duplicating handles passed in pass_handle ().

ACE_TCHAR** ACE_Process_Options::environment_argv_`[protected]`

| Pointers into environment_buf_.

int ACE_Process_Options::environment_argv_index_`[protected]`

| Pointer to environment_argv_.

ACE_TCHAR* ACE_Process_Options::environment_buf_`[protected]`

| Pointer to buffer of the environment settings.

size_t ACE_Process_Options::environment_buf_index_`[protected]`

| Pointer into environment_buf_. This should point to the next free spot.

size_t ACE_Process_Options::environment_buf_len_`[protected]`

| Size of the environment buffer. Configurable.

int ACE_Process_Options::environment_inherited_`[protected]`

| Ensures once only call to inherit environment.

BOOL ACE_Process_Options::handle_inheritence_`[protected]`

| Default TRUE.

ACE_Handle_Set ACE_Process_Options::handles_passed_`[protected]`

| Set of handles that were passed in pass_handle ().

int ACE_Process_Options::inherit_environment_`[protected]`

| Whether the child process inherits the current process environment.

int ACE_Process_Options::max_environ_argv_index_`[protected]`

| Maximum index of environment_argv_ buffer.

int ACE_Process_Options::max_environment_args_`[protected]`

| Maximum number of environment variables. Configurable.

LPSECURITY_ATTRIBUTES ACE_Process_Options::process_attributes_`[protected]`

| Pointer to security_buf1_.

pid_t ACE_Process_Options::process_group_`[protected]`

| Process-group on Unix; unused on Win32.

ACE_TCHAR ACE_Process_Options::process_name_[MAXPATHLEN + 1]`[protected]`

| Pathname for the process. Relative path or absolute path or just the program name.

SECURITY_ATTRIBUTES ACE_Process_Options::security_buf1_`[protected]`

| Data for process_attributes_.

SECURITY_ATTRIBUTES ACE_Process_Options::security_buf2_`[protected]`

| Data for thread_attributes_.

int ACE_Process_Options::set_handles_called_`[protected]`

| Is 1 if stdhandles was called.

ACE_TEXT_STARTUPINFO ACE_Process_Options::startup_info_`[protected]`

LPSECURITY_ATTRIBUTES ACE_Process_Options::thread_attributes_`[protected]`

| Pointer to security_buf2_.

ACE_TCHAR ACE_Process_Options::working_directory_[MAXPATHLEN + 1]`[protected]`

| The current working directory.

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

- Process.h
- Process.cpp
- Process.i