---

ACE_Process_Options Class Reference

Process Options. More...

#include <Process.h>

Collaboration diagram for ACE_Process_Options:

[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)
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_TCHAR *	process_name (void)
u_long	creation_flags (void) const
	Get the creation flags.
void	creation_flags (u_long)
	Set the creation flags.
ACE_TCHAR *	working_directory (void)
	Current working directory. Returns "" if nothing has been set.
ACE_TCHAR *	command_line_buf (int *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_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 Methods
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_TCHAR *	environment_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_TCHAR *	command_line_buf_
	Pointer to buffer of command-line arguments. E.g., "-f foo -b bar".
ACE_TCHAR *	command_line_copy_
int	command_line_buf_len_
	Max length of command_line_buf_.
ACE_TCHAR *	command_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

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    )

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 (\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_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 '\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. 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:

• Process.h
• Process.cpp
• Process.i

---