<QtEnvironmentVariables> | Qt Core | Qt 6.11.2
Description: Helper functions for working with environment variables.

- Qt 6.11
- Qt Core
- <QtEnvironmentVariables>
- Qt 6.11.2 Reference Documentation

# <QtEnvironmentVariables>

Helper functions for working with environment variables. More...

Header: | `#include <QtEnvironmentVariables>`

## Functions

QString | qEnvironmentVariable(const char *varName)
QString | qEnvironmentVariable(const char *varName, const QString &defaultValue)
int | qEnvironmentVariableIntValue(const char *varName, bool *ok = nullptr)
`(since 6.10)` std::optional<qint64> | qEnvironmentVariableIntegerValue(const char *varName)
bool | qEnvironmentVariableIsEmpty(const char *varName)
bool | qEnvironmentVariableIsSet(const char *varName)
QByteArray | qgetenv(const char *varName)
bool | qputenv(const char *varName, QByteArrayView value)
bool | qunsetenv(const char *varName)

## Detailed Description

The functions in this header are used to manipulate the environment variables.

##### Thread-safety

The Qt environment manipulation functions are thread-safe, but this requires that the C library equivalent functions like `getenv` and `putenv` are not directly called.

This is also relevant for the third-party libraries that are loaded by the application. If such a library uses unsafe functions to manipulate the environment from a secondary thread, it is recommended to do all the environment setup in the main thread before loading the library and/or creating secondary threads.

## Function Documentation

### QString qEnvironmentVariable(const char *varName, const QString &defaultValue)

### QString qEnvironmentVariable(const char *varName)

These functions return the value of the environment variable, varName, as a QString. If no variable varName is found in the environment and defaultValue is provided, defaultValue is returned. Otherwise QString() is returned.

The Qt environment manipulation functions are thread-safe, but this requires that the C library equivalent functions like getenv and putenv are not directly called.

The following table describes how to choose between qgetenv() and qEnvironmentVariable():

Condition | Recommendation
--- | ---
Variable contains file paths or user text | qEnvironmentVariable()
Windows-specific code | qEnvironmentVariable()
Unix-specific code, destination variable is not QString and/or is used to interface with non-Qt APIs | qgetenv()
Destination variable is a QString | qEnvironmentVariable()
Destination variable is a QByteArray or std::string | qgetenv()

Note: on Unix systems, this function may produce data loss if the original string contains arbitrary binary data that cannot be decoded by the locale codec. Use qgetenv() instead for that case. On Windows, this function is lossless.

Note: the variable name varName must contain only US-ASCII characters.

See also qputenv(), qgetenv(), qEnvironmentVariableIsSet(), qEnvironmentVariableIsEmpty(), and qEnvironmentVariableIntegerValue().

### `[noexcept]` int qEnvironmentVariableIntValue(const char *varName, bool *ok = nullptr)

Returns the numerical value of the environment variable varName. If ok is not null, sets `*ok` to `true` or `false` depending on the success of the conversion.

Equivalent to

        int to_int = qgetenv(varName).toInt(ok, 0);

except that it's much faster, and can't throw exceptions.

See also qgetenv(), qEnvironmentVariable(), and qEnvironmentVariableIsSet().

### `[noexcept, since 6.10]` std::optional<qint64> qEnvironmentVariableIntegerValue(const char *varName)

Returns the numerical value of the environment variable varName. If the variable is not set or could not be parsed as an integer, it returns `std::nullopt`.

Similar to

        int to_int = qgetenv(varName).toInt(ok, 0);

except that it's much faster, and can't throw exceptions.

If a value of zero is semantically the same as an empty or unset variable, applications can use

        auto value = qEnvironmentVariableIntegerValue(varName).value_or(0);

Do note in this case that failures to parse a value will also produce a zero.

But if a value of zero can be used to disable some functionality, applications can compare the returned `std::optional` to zero, which will only be true if the variable was set and contained a number that parsed as zero, as in:

        bool equals_zero = qEnvironmentVariableIntegerValue(varName) == 0;

This function was introduced in Qt 6.10.

See also qgetenv(), qEnvironmentVariable(), and qEnvironmentVariableIsSet().

### `[noexcept]` bool qEnvironmentVariableIsEmpty(const char *varName)

Returns whether the environment variable varName is empty.

Equivalent to

        bool is_empty = qgetenv(varName).isEmpty();

except that it's potentially much faster, and can't throw exceptions.

See also qgetenv(), qEnvironmentVariable(), and qEnvironmentVariableIsSet().

### `[noexcept]` bool qEnvironmentVariableIsSet(const char *varName)

Returns whether the environment variable varName is set.

Equivalent to

        bool is_not_null = !qgetenv(varName).isNull();

except that it's potentially much faster, and can't throw exceptions.

See also qgetenv(), qEnvironmentVariable(), qEnvironmentVariableIsEmpty(), and qEnvironmentVariableIntegerValue().

### QByteArray qgetenv(const char *varName)

Returns the value of the environment variable with name varName as a QByteArray. If no variable by that name is found in the environment, this function returns a default-constructed QByteArray.

The Qt environment manipulation functions are thread-safe, but this requires that the C library equivalent functions like getenv and putenv are not directly called.

To convert the data to a QString use QString::fromLocal8Bit().

Note: on desktop Windows, qgetenv() may produce data loss if the original string contains Unicode characters not representable in the ANSI encoding. Use qEnvironmentVariable() instead. On Unix systems, this function is lossless.

Note: This function is thread-safe.

See also qputenv(), qEnvironmentVariable(), qEnvironmentVariableIsSet(), qEnvironmentVariableIsEmpty(), and qEnvironmentVariableIntegerValue().

### bool qputenv(const char *varName, QByteArrayView value)

This function sets the value of the environment variable named varName. It will create the variable if it does not exist. It returns 0 if the variable could not be set.

Calling qputenv with an empty value removes the environment variable on Windows, and makes it set (but empty) on Unix. Prefer using qunsetenv() for fully portable behavior.

Note: qputenv() was introduced because putenv() from the standard C library was deprecated in VC2005 (and later versions). qputenv() uses the replacement function in VC, and calls the standard C library's implementation on all other platforms.

Note: In Qt versions prior to 6.5, the value argument was QByteArray, not QByteArrayView.

See also qgetenv() and qEnvironmentVariable().

### bool qunsetenv(const char *varName)

This function deletes the variable varName from the environment.

Returns `true` on success.

See also qputenv(), qgetenv(), and qEnvironmentVariable().