| Home | Libraries | People | FAQ | More

## Global env

boost::process::env

## Synopsis

    // In header: <boost/process/env.hpp>

    unspecified env;

## Description

The `env` property provides a functional way to modify the environment used by the child process. If none is passed the environment is inherited from the father process. Appending means that the environment will be interpreted as a ';' or ':' separated list as used in `PATH`.

On both `posix` and `windows` the environment variables can be lists of strings, separated by ';'. This is typically used for the `PATH` variable.

By default the environment will be inherited from the launching process, which is also true if environment are modified with this initializer.

## Details

### Operations

#### Setting variables

To set a variable `id` the value `value` the following syntax can be used.

    env[id] = value;
    env(id, value);

`std::initializer_list` is among the allowed types, so the following syntax is also possible.

    env[id] = {value1, value2};
    env(id, {value1, value2});

| Note
Creates the variable if it does not exist.

The following lists contain possible value types, with `char_type` being either `char` or `wchar_t` for both `id` and `value`.

##### id

- `std::basic_string<char_type>`

- `const char_type *`

##### value

- `std::basic_string<char_type>`

- `const char_type *`

- `std::initializer_list<const char_type *>`

- `std::vector<std::basic_string<char_type>>`

| Note
Using `std::vector` or `std::initializer_list`

#### Append variables

Appending means, that a variable will be interpreted as a To append a variable `id` the value `value` the following syntax can be used:

    env[id] += value;

`std::initializer_list` is among the allowed types, so the following syntax is also possible.

    env[id] += {value1, value2};

| Note
Creates the variable if it does not exist.

The following lists contain possible value types, with `char_type` being either `char` or `wchar_t` for both `id` and `value`.

##### id

- `std::basic_string<char_type>`

- `const char_type *`

##### value

- `std::basic_string<char_type>`

- `const char_type *`

- `std::initializer_list<const char_type *>`

- `std::vector<std::basic_string<char_type>>`

#### Reset variables

Reseting signle variables can be done in the following way:

    env[id] = boost::none;
    env(id, boost::none);

| Note
This does not set the value empty, but removes it from the list.

The following lists contain possible value types, with `char_type` being either `char` or `wchar_t`:

##### id

- `std::basic_string<char_type>`

- `const char_type *`

#### Initialize the environment

The whole environment can be initialized from an object of type boost::process::environment

    env=env;
    env(env);

| Note
The passed `environment` can also be default-constructed to get an empty environment.

##### id

- `std::basic_string<char_type>`

- `const char_type *`

##### value

- `boost::process::basic_environment<char_type>`

### Example

    spawn("b2", env["PATH"]+="F:/boost", env["SOME_VAR"]=boost::none, env["NEW_VAR"]="VALUE");

If the overload style should be done by passing an instance of boost::process::environment the above example would look like this.

    environment e = this_process::environment();
    e["PATH"]   += "F:/boost";
    e.erase("SOME_VAR");
    e["NEW_VAR"] = "VALUE";
    spawn("b2", e);

| Warning
Passing an empty environment will cause undefined behaviour.