<QtEnvironmentVariables> Proxy Page
Functions
| QString | qEnvironmentVariable(const char *varName, const QString &defaultValue) |
| QString | qEnvironmentVariable(const char *varName) |
| int | qEnvironmentVariableIntValue(const char *varName, bool *ok = nullptr) |
| 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) |
Function Documentation
QString qEnvironmentVariable(const char *varName)
QString qEnvironmentVariable(const char *varName, const QString &defaultValue)
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(), and qEnvironmentVariableIsEmpty().
QString qEnvironmentVariable(const char *varName, const QString &defaultValue)
QString qEnvironmentVariable(const char *varName)
[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
qgetenv(varName).toInt(ok, 0)
except that it's much faster, and can't throw exceptions.
Note: there's a limit on the length of the value, which is sufficient for all valid values of int, not counting leading zeroes or spaces. Values that are too long will either be truncated or this function will set ok to false.
See also qgetenv(), qEnvironmentVariable(), and qEnvironmentVariableIsSet().
[noexcept] bool qEnvironmentVariableIsEmpty(const char *varName)
Returns whether the environment variable varName is empty.
Equivalent to
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
!qgetenv(varName).isNull()
except that it's potentially much faster, and can't throw exceptions.
See also qgetenv(), qEnvironmentVariable(), and qEnvironmentVariableIsEmpty().
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(), and qEnvironmentVariableIsEmpty().
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().