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

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

ACE_INLINE void ACE_Process_Options::avoid_zombies ( | int avoid_zombies )

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

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

| Same as above in argv format. 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 exactly what was passed to this->command_line. If max_len is not 0, receives the maximum length of the command line buffer.

ACE_INLINE void ACE_Process_Options::creation_flags ( | u_long cf )

ACE_INLINE u_long ACE_Process_Options::creation_flags ( | void ) const

| Get the creation flags. Set the creation flags.

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

| Get a copy of the handles the ACE_Process_Options duplicated for the spawned process. 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

| On UNIX, these methods are used by the 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 )

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

| Get a copy of the handles passed to the spawned process. This will be the set of handles previously passed to pass_handle(). 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].

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,
| int len )`[protected]`

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

ACE_INLINE pid_t ACE_Process_Options::setgroup ( | pid_t pgrp )

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.

int ACE_Process_Options::environment_buf_index_`[protected]`

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

int 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