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:

Collaboration graph
[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_TCHARprocess_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_TCHARworking_directory (void)
 Current working directory. Returns "" if nothing has been set.

ACE_TCHARcommand_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_TCHARenv_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 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_TCHARenvironment_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_TCHARcommand_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_TCHARcommand_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

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:
Generated at Wed Nov 21 10:32:45 2001 for ACE by doxygen1.2.3 written by Dimitri van Heesch, © 1997-2000