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 Member Functions

 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)
void release_handles (void)
 Release the standard handles previously set with set_handles;.
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.
void working_directory (const char *wd)
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 ().
int command_line (const ACE_TCHAR *const argv[])
 Same as above in argv format. <argv> must be null terminated.
void process_name (const ACE_TCHAR *name)
const ACE_TCHARprocess_name (void)
u_long creation_flags (void) const
 Get the creation flags.
void creation_flags (u_long)
 Set the creation flags.
ACE_TCHARworking_directory (void)
 Current working directory. Returns "" if nothing has been set.
ACE_TCHARcommand_line_buf (int *max_len=0)
ACE_TCHAR *const * command_line_argv (void)
ACE_TCHARenv_buf (void)
pid_t getgroup (void) const
pid_t setgroup (pid_t pgrp)
int handle_inheritence (void)
void handle_inheritence (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).
int avoid_zombies (void)
 Get current value for avoid_zombies.
ACE_TEXT_STARTUPINFO * startup_info (void)
 Used for setting and getting.
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

int inherit_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.
size_t environment_buf_index_
int environment_argv_index_
 Pointer to environment_argv_.
ACE_TCHARenvironment_buf_
 Pointer to buffer of the environment settings.
size_t 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".
ACE_TCHARcommand_line_copy_
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]

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
 

Enumerator:
DEFAULT_COMMAND_LINE_BUF_LEN 
NO_EXEC 

anonymous enum [protected]
 

Enumerator:
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   ) 
 

Get current value for avoid_zombies.

ACE_INLINE void ACE_Process_Options::avoid_zombies int   ) 
 

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 () 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_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 ''. [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   ) 
 

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.

ACE_INLINE LPSECURITY_ATTRIBUTES ACE_Process_Options::get_process_attributes void   )  const
 

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

ACE_INLINE 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   ) 
 

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   ) 
 

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 name  ) 
 

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   ) 
 

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. Returns 0 on success, -1 on failure.

ACE_INLINE LPSECURITY_ATTRIBUTES ACE_Process_Options::set_process_attributes void   ) 
 

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

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

Parameters:
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_INLINE 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.

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

ACE_TCHAR* ACE_Process_Options::command_line_copy_ [protected]
 

Pointer to copy of command-line arguments, which is needed when converting a command-line string into a command-line argv.

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:
Generated on Wed Nov 23 15:49:58 2005 for ACE by  doxygen 1.4.5