ACE
6.3.3
|
Process Options. More...
#include <Process.h>
Public Types | |
enum | { DEFAULT_COMMAND_LINE_BUF_LEN = 1024, NO_EXEC = 0 } |
Public Member Functions | |
ACE_Process_Options (bool inherit_environment=true, size_t command_line_buf_len=DEFAULT_COMMAND_LINE_BUF_LEN, size_t env_buf_len=ENVIRONMENT_BUFFER, size_t max_env_args=MAX_ENVIRONMENT_ARGS, size_t max_cmdline_args=MAX_COMMAND_LINE_OPTIONS) | |
~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) |
void | release_handles (void) |
Release the standard handles previously set with set_handles;. More... | |
int | setenv (const ACE_TCHAR *format,...) |
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. More... | |
void | working_directory (const char *wd) |
void | working_directory (const wchar_t *wd) |
wchar_t version of working_directory More... | |
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. argv must be null terminated. More... | |
void | process_name (const ACE_TCHAR *name) |
const ACE_TCHAR * | process_name (void) |
u_long | creation_flags (void) const |
Get the creation flags. More... | |
void | creation_flags (u_long) |
ACE_TCHAR * | working_directory (void) |
Current working directory. Returns "" if nothing has been set. More... | |
ACE_TCHAR * | command_line_buf (size_t *max_len=0) |
ACE_TCHAR *const * | command_line_argv (void) |
ACE_TCHAR * | env_buf (void) |
pid_t | getgroup (void) const |
pid_t | setgroup (pid_t pgrp) |
int | handle_inheritance (void) |
void | handle_inheritance (int) |
int | pass_handle (ACE_HANDLE) |
int | dup_handles (ACE_Handle_Set &set) const |
int | passed_handles (ACE_Handle_Set &set) const |
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... | |
void | enable_unicode_environment (void) |
void | disable_unicode_environment (void) |
Disable the use of a Unicode environment. More... | |
bool | use_unicode_environment (void) const |
Return the unicode environment status. More... | |
ACE_TEXT_STARTUPINFO * | startup_info (void) |
Used for setting and getting. More... | |
LPSECURITY_ATTRIBUTES | get_process_attributes (void) const |
LPSECURITY_ATTRIBUTES | set_process_attributes (void) |
LPSECURITY_ATTRIBUTES | get_thread_attributes (void) const |
LPSECURITY_ATTRIBUTES | set_thread_attributes (void) |
Protected Types | |
enum | { MAX_COMMAND_LINE_OPTIONS = 128, ENVIRONMENT_BUFFER = 16 * 1024, MAX_ENVIRONMENT_ARGS = 512 } |
Protected Member Functions | |
int | setenv_i (ACE_TCHAR *assignment, size_t len) |
void | inherit_environment (void) |
Protected Attributes | |
bool | inherit_environment_ |
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_ |
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... | |
bool | handle_inheritance_ |
Default true. More... | |
int | set_handles_called_ |
Is 1 if stdhandles was called. More... | |
size_t | environment_buf_index_ |
size_t | 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... | |
size_t | max_environment_args_ |
Maximum number of environment variables. Configurable. More... | |
size_t | max_environ_argv_index_ |
Maximum index of environment_argv_ buffer. More... | |
ACE_TCHAR | working_directory_ [MAXPATHLEN+1] |
The current working directory. More... | |
bool | 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... | |
ACE_TCHAR * | command_line_copy_ |
size_t | command_line_buf_len_ |
Max length of command_line_buf_. More... | |
size_t | max_command_line_args_ |
Maximum number of command-line arguments. Configurable. More... | |
ACE_TCHAR ** | command_line_argv_ |
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] |
bool | use_unicode_environment_ |
Indicate if a Unicode environment should be used. More... | |
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.
|
protected |
ACE_Process_Options::ACE_Process_Options | ( | bool | inherit_environment = true , |
size_t | command_line_buf_len = DEFAULT_COMMAND_LINE_BUF_LEN , |
||
size_t | env_buf_len = ENVIRONMENT_BUFFER , |
||
size_t | max_env_args = MAX_ENVIRONMENT_ARGS , |
||
size_t | max_cmdline_args = MAX_COMMAND_LINE_OPTIONS |
||
) |
If inherit_environment == true, 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.
|
inline |
Set value for avoid_zombies (has no real effect except on *nix).
|
inline |
Get current value for avoid_zombies.
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.
int ACE_Process_Options::command_line | ( | const ACE_ANTI_TCHAR * | format, |
... | |||
) |
Anti-TChar version of command_line ()
int ACE_Process_Options::command_line | ( | const ACE_TCHAR *const | argv[] | ) |
Same as above in argv format. argv must be null terminated.
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.
|
inline |
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.
|
inline |
Get the creation flags.
|
inline |
Set the creation flags to affect how a new process is spawned. The only ACE-defined flag is NO_EXEC
which prevents the new process from executing a new program image; this is a simple POSIX fork(). The NO_EXEC
option has no affect on Windows; on other platforms where a POSIX fork is not possible, specifying NO_EXEC
will cause ACE_Process::spawn() to fail.
On Windows, the value of creation_flags is passed to the CreateProcess
system call as the value of the dwCreationFlags
parameter.
|
inline |
Disable the use of a Unicode environment.
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
|
inline |
Enable the use of a Unicode environment. This only makes sense for Win32 when ACE_USES_WCHAR is not defined.
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.
|
inline |
Get the process_attributes. Returns NULL if set_process_attributes has not been set.
|
inline |
Get the thread_attributes. Returns NULL if set_thread_attributes has not been set.
|
inline |
Get the process group. On UNIX, these methods are used by the ACE_Process_Manager to manage groups of processes.
|
inline |
Allows disabling of handle inheritance, default is TRUE.
|
inline |
|
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
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
|
inline |
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].
|
inline |
Return the process_name. If the <process_name(name)> set method is not called, this method will return argv[0].
void ACE_Process_Options::release_handles | ( | void | ) |
Release 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.
|
inline |
If this is called, a non-null process attributes is sent to CreateProcess.
|
inline |
If this is called, a non-null thread attributes is sent to CreateProcess.
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. |
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 | ( | ACE_TCHAR * | envp[] | ) |
Same as above with argv format. envp must be null terminated.
|
protected |
Add assignment to environment_buf_ and adjust environment_argv_. len is the strlen of assignment.
|
inline |
Set the process group. On UNIX, these methods are used by the ACE_Process_Manager to manage groups of processes.
|
inline |
Used for setting and getting.
|
inline |
Return the unicode environment status.
|
inline |
Set the working directory for the process. strlen of wd must be <= MAXPATHLEN.
|
inline |
wchar_t version of working_directory
|
inline |
Current working directory. Returns "" if nothing has been set.
|
protected |
Avoid zombies for spawned processes.
|
protected |
Argv-style command-line arguments.
|
protected |
Ensures command_line_argv is only calculated once.
|
protected |
Pointer to buffer of command-line arguments. E.g., "-f foo -b bar".
|
protected |
Max length of command_line_buf_.
|
protected |
Pointer to copy of command-line arguments, which is needed when converting a command-line string into a command-line argv.
|
protected |
Default 0.
|
protected |
Results of duplicating handles passed in pass_handle ().
|
protected |
Pointers into environment_buf_.
|
protected |
Pointer to environment_argv_.
|
protected |
Pointer to buffer of the environment settings.
|
protected |
Pointer into environment_buf_. This should point to the next free spot.
|
protected |
Size of the environment buffer. Configurable.
|
protected |
Ensures once only call to inherit environment.
|
protected |
Default true.
|
protected |
Set of handles that were passed in pass_handle ().
|
protected |
Whether the child process inherits the current process environment.
|
protected |
Maximum number of command-line arguments. Configurable.
|
protected |
Maximum index of environment_argv_ buffer.
|
protected |
Maximum number of environment variables. Configurable.
|
protected |
Pointer to security_buf1_.
|
protected |
Process-group on Unix; unused on Win32.
|
protected |
Pathname for the process. Relative path or absolute path or just the program name.
|
protected |
Data for process_attributes_.
|
protected |
Data for thread_attributes_.
|
protected |
Is 1 if stdhandles was called.
|
protected |
|
protected |
Pointer to security_buf2_.
|
protected |
Indicate if a Unicode environment should be used.
|
protected |
The current working directory.