ACE_Process_Options Class Reference

Process Options. More...

#include <Process.h>

Collaboration diagram for ACE_Process_Options:

Collaboration graph
List of all members.

Public Types


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


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.
BOOL handle_inheritence_
 Default TRUE.
LPSECURITY_ATTRIBUTES process_attributes_
 Pointer to security_buf1_.
LPSECURITY_ATTRIBUTES thread_attributes_
 Pointer to security_buf2_.
 Data for process_attributes_.
 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_.
 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.
 Pointer to buffer of command-line arguments. E.g., "-f foo -b bar".
int command_line_buf_len_
 Max length of command_line_buf_.
 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


anonymous enum [protected]


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   ) 


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

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

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,

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

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