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 (bool inherit_environment=true, 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)
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_inheritance (void)
 Allows disabling of handle inheritance, default is TRUE.
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).
int avoid_zombies (void)
 Get current value for avoid_zombies.
void enable_unicode_environment (void)
void disable_unicode_environment (void)
 Disable the use of a Unicode environment.
bool use_unicode_environment (void) const
 Return the unicode environment status.
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)
ACE_TCHAR *const * env_argv (void)
 argv-style array of environment settings.
ACE_HANDLE get_stdin (void) const
ACE_HANDLE get_stdout (void) const
ACE_HANDLE get_stderr (void) const
int setreugid (const ACE_TCHAR *user)
void setruid (uid_t id)
void seteuid (uid_t id)
void setrgid (uid_t id)
void setegid (uid_t id)
uid_t getruid (void) const
uid_t geteuid (void) const
uid_t getrgid (void) const
uid_t getegid (void) const
bool inherit_environment (void) const
void inherit_environment (bool nv)

Protected Types


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.
int avoid_zombies_
 Avoid zombies for spawned processes.
int environment_inherited_
 Ensures once only call to inherit environment.
LPSECURITY_ATTRIBUTES process_attributes_
 Pointer to security_buf1_.
LPSECURITY_ATTRIBUTES thread_attributes_
 Pointer to security_buf2_.
 Data for process_attributes_.
 Data for thread_attributes_.
ACE_HANDLE stdout_
ACE_HANDLE stderr_
uid_t ruid_
uid_t euid_
uid_t rgid_
uid_t egid_
bool handle_inheritance_
 Default true.
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]
bool use_unicode_environment_
 Indicate if a Unicode environment should be used.

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]
These sizes should be taken from the appropriate POSIX/system header files and/or defined dynamically.

Constructor & Destructor Documentation

ACE_Process_Options::ACE_Process_Options ( bool  inherit_environment = true,
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 == 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   ) 


Member Function Documentation

int ACE_Process_Options::avoid_zombies ( void   ) 

Get current value for avoid_zombies.

void ACE_Process_Options::avoid_zombies ( int  avoid_zombies  ) 

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

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_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.
void ACE_Process_Options::creation_flags ( u_long  cf  ) 

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.

u_long ACE_Process_Options::creation_flags ( void   )  const

Get the creation flags.

void ACE_Process_Options::disable_unicode_environment ( void   ) 

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

  • pass_handle are returned in
  • set.
    0 if there were no handles to return; 1 if there were.
void ACE_Process_Options::enable_unicode_environment ( void   ) 

Enable the use of a Unicode environment. This only makes sense for Win32 when ACE_USES_WCHAR is not defined.

ACE_TCHAR *const * ACE_Process_Options::env_argv ( void   ) 

argv-style array of environment settings.

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.

ACE_HANDLE ACE_Process_Options::get_stderr ( void   )  const
ACE_HANDLE ACE_Process_Options::get_stdin ( void   )  const
ACE_HANDLE ACE_Process_Options::get_stdout ( void   )  const
LPSECURITY_ATTRIBUTES ACE_Process_Options::get_thread_attributes ( void   )  const

Get the thread_attributes. Returns NULL if set_thread_attributes has not been set.

uid_t ACE_Process_Options::getegid ( void   )  const
uid_t ACE_Process_Options::geteuid ( void   )  const
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.

uid_t ACE_Process_Options::getrgid ( void   )  const
uid_t ACE_Process_Options::getruid ( void   )  const
void ACE_Process_Options::handle_inheritance ( int  hi  ) 
int ACE_Process_Options::handle_inheritance ( void   ) 

Allows disabling of handle inheritance, default is TRUE.

void ACE_Process_Options::inherit_environment ( void   )  [protected]

Helper function to grab win32 environment and stick it in environment_buf_ using this->setenv_i.

void ACE_Process_Options::inherit_environment ( bool  nv  ) 

Set the inherit_environment flag.

bool ACE_Process_Options::inherit_environment ( void   )  const

Get the inherit_environment flag.

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.
    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.
    0 if there were no handles to return; 1 if there were.
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].

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.

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.

void ACE_Process_Options::setegid ( uid_t  id  ) 
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 
) [protected]

Add assignment to environment_buf_ and adjust environment_argv_. len is the strlen of assignment.

void ACE_Process_Options::seteuid ( uid_t  id  ) 
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.

int ACE_Process_Options::setreugid ( const ACE_TCHAR user  ) 
void ACE_Process_Options::setrgid ( uid_t  id  ) 
void ACE_Process_Options::setruid ( uid_t  id  ) 
ACE_TEXT_STARTUPINFO* ACE_Process_Options::startup_info ( void   ) 

Used for setting and getting.

bool ACE_Process_Options::use_unicode_environment ( void   )  const

Return the unicode environment status.

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

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

Avoid zombies for spawned processes.

ACE_TCHAR* ACE_Process_Options::command_line_argv_[MAX_COMMAND_LINE_OPTIONS] [protected]

Argv-style command-line arguments.

Ensures command_line_argv is only calculated once.

Pointer to buffer of command-line arguments. E.g., "-f foo -b bar".

Max length of command_line_buf_.

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

Default 0.

Results of duplicating handles passed in pass_handle ().

uid_t ACE_Process_Options::egid_ [protected]

Pointers into environment_buf_.

Pointer to environment_argv_.

Pointer to buffer of the environment settings.

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

Size of the environment buffer. Configurable.

Ensures once only call to inherit environment.

uid_t ACE_Process_Options::euid_ [protected]

Default true.

Set of handles that were passed in pass_handle ().

Whether the child process inherits the current process environment.

Maximum index of environment_argv_ buffer.

Maximum number of environment variables. Configurable.

LPSECURITY_ATTRIBUTES ACE_Process_Options::process_attributes_ [protected]

Pointer to security_buf1_.

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.

uid_t ACE_Process_Options::rgid_ [protected]
uid_t ACE_Process_Options::ruid_ [protected]
SECURITY_ATTRIBUTES ACE_Process_Options::security_buf1_ [protected]

Data for process_attributes_.

SECURITY_ATTRIBUTES ACE_Process_Options::security_buf2_ [protected]

Data for thread_attributes_.

Is 1 if stdhandles was called.

ACE_TEXT_STARTUPINFO ACE_Process_Options::startup_info_ [protected]
ACE_HANDLE ACE_Process_Options::stderr_ [protected]
ACE_HANDLE ACE_Process_Options::stdin_ [protected]
ACE_HANDLE ACE_Process_Options::stdout_ [protected]
LPSECURITY_ATTRIBUTES ACE_Process_Options::thread_attributes_ [protected]

Pointer to security_buf2_.

Indicate if a Unicode environment should be used.

The current working directory.

The documentation for this class was generated from the following files:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on Fri Sep 11 03:57:41 2009 for ACE by  doxygen 1.6.1