---
name: "ACE_Process_Options"
section: "3"
platform: "linux"
package: "libace-doc"
version: "5.0.7-4"
release: "Debian 2.2 (Potato)"
platforms: ["linux"]
url: "https://new.carta.tech/ACE_Process_Options"
---

# ACE\_Process\_Options(3)

Process Options

## NAME

ACE\_Process\_Options -  Process Options

## SYNOPSIS

```
#include <ace/Process.h>
class ACE_Process_Options
{
  public:
    enum{ DEFAULT_COMMAND_LINE_BUF_LEN = 1024, #if defined (
        ACE_WIN32) NO_EXEC = 0 #else NO_EXEC = 1 #endif };

    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);
    int set_handles (
        ACE_HANDLE std_in,
        ACE_HANDLE std_out = ACE_INVALID_HANDLE,
        ACE_HANDLE std_err = ACE_INVALID_HANDLE
        );
    int setenv (LPCTSTR format, ...);
    int setenv (LPCTSTR variable_name, LPCTSTR format, ...);
    int setenv (LPTSTR envp[]);
    void working_directory (LPCTSTR wd);
    int command_line (LPCTSTR format, ...);
    int command_line (LPCTSTR const argv[]);
    u_long creation_flags (void) const;
    void creation_flags (u_long);
    LPTSTR working_directory (void);
    LPTSTR command_line_buf (void);
    LPTSTR env_buf (void);
    pid_t getgroup (void) const;
    pid_t setgroup (pid_t pgrp);
    STARTUPINFO *startup_info (void);
    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);
    int handle_inheritence (void);
    void handle_inheritence (int);
    char *const *command_line_argv (void);
    char *const *env_argv (void);
    ACE_HANDLE get_stdin (void);
    ACE_HANDLE get_stdout (void);
    ACE_HANDLE get_stderr (void);
    void avoid_zombies (int);
    int avoid_zombies (void);
  protected:
        enum{ MAX_COMMAND_LINE_OPTIONS = 128,
        ENVIRONMENT_BUFFER = 16 * 1024,
        MAX_ENVIRONMENT_ARGS = 512 };

    int setenv_i (LPTSTR assignment, int len);
    int inherit_environment_;
    u_long creation_flags_;
    void inherit_environment (void);
    int environment_inherited_;
    STARTUPINFO startup_info_;
    BOOL handle_inheritence_;
    LPSECURITY_ATTRIBUTES process_attributes_;
    LPSECURITY_ATTRIBUTES thread_attributes_;
    SECURITY_ATTRIBUTES security_buf1_;
    SECURITY_ATTRIBUTES security_buf2_;
    ACE_HANDLE stdin_;
    ACE_HANDLE stdout_;
    ACE_HANDLE stderr_;
    int avoid_zombies_;
    int set_handles_called_;
    int environment_buf_index_;
    int environment_argv_index_;
    LPTSTR environment_buf_;
    int environment_buf_len_;
    LPTSTR* environment_argv_;
    int max_environment_args_;
    int max_environ_argv_index_;
    TCHAR working_directory_[MAXPATHLEN + 1];
    int command_line_argv_calculated_;
    LPTSTR command_line_buf_;
    LPTSTR command_line_argv_[MAX_COMMAND_LINE_OPTIONS];
    pid_t process_group_;
};
```

## DESCRIPTION

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.

## Default settings not part of public Interface.

@@ These sizes should be taken from the appropriate POSIX/system header files and/or defined dynamically.

## Methods to set process creation options portably.

```
int 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.

```
int setenv (LPCTSTR format, ...);
```

format must be of the form "VARIABLE=VALUE".  There can not be any spaces between VARIABLE and the equal sign.

```
int setenv (LPCTSTR variable_name, LPCTSTR 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 setenv (LPTSTR envp[]);
```

Same as above with argv format.  envp must be null terminated.

```
void working_directory (LPCTSTR wd);
```

Set the working directory for the process.  strlen of wd must be = MAXPATHLEN.

```
int command_line (LPCTSTR 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.

```
int command_line (LPCTSTR const argv[]);
```

Same as above in argv format.  argv must be null terminated.

```
u_long creation_flags (void) const;
```

Get the creation flags.

```
void creation_flags (u_long);
```

Set the creation flags.

\= ACE\_Process uses these operations to retrieve option values.

```
LPTSTR working_directory (void);
```

Current working directory.  Returns "" if nothing has been set.

```
LPTSTR command_line_buf (void);
```

Buffer of command-line options.  Returns exactly what was passed to this-command\_line.

```
LPTSTR 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.

## Get/set process group.

```
pid_t getgroup (void) const;
```

```
pid_t setgroup (pid_t pgrp);
```

On UNIX, these methods are used by the ACE\_Process\_Manager to manage groups of processes.

## Non-portable accessors for when you just have to use them.""

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

```
int handle_inheritence (void);
```

Default is TRUE.

```
void handle_inheritence (int);
```

Allows disabling of handle inheritence.

```
char *const *command_line_argv (void);
```

argv-style command-line options.  Parses and modifies the string created from this-command\_line.  All spaces not in quotes ("" or and returned with each entry pointing to the start of null-terminated string.  Returns { 0 } if nothing has been set.

```
char *const *env_argv (void);
```

argv-style array of environment settings.

## Accessors for the standard handles.

```
ACE_HANDLE get_stdin (void);
```

```
ACE_HANDLE get_stdout (void);
```

```
ACE_HANDLE get_stderr (void);
```

```
void avoid_zombies (int);
```

Set value for avoid\_zombies.

```
int avoid_zombies (void);
```

Get current value for avoid\_zombies.

## AUTHOR

Tim Harrison harrison@cs.wustl.edu

## LIBRARY

ace