En esta página

<QtEnvironmentVariables>

Funciones auxiliares para trabajar con variables de entorno. Más...

Header: #include <QtEnvironmentVariables>

Funciones

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)

Descripción detallada

Las funciones de este encabezado se utilizan para manipular las variables de entorno.

Seguridad entre subprocesos

Las funciones de manipulación del entorno de Qt son seguras para subprocesos, pero esto requiere que no se llamen directamente a las funciones equivalentes de la biblioteca C, como getenv y putenv.

Esto también es relevante para las bibliotecas de terceros que carga la aplicación. Si una biblioteca de este tipo utiliza funciones no seguras para manipular el entorno desde un hilo secundario, se recomienda realizar toda la configuración del entorno en el hilo principal antes de cargar la biblioteca y/o crear hilos secundarios.

Documentación de funciones

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

QString qEnvironmentVariable(const char *varName)

Estas funciones devuelven el valor de la variable de entorno ` varName` como un objeto ` QString`. Si no se encuentra ninguna variable ` varName ` en el entorno y se proporciona ` defaultValue `, se devuelve ` defaultValue `. En caso contrario, se devuelve `QString()`.

Las funciones de manipulación del entorno de Qt son seguras para subprocesos, pero esto requiere que no se llamen directamente a las funciones equivalentes de la biblioteca C, como getenv y putenv.

La siguiente tabla describe cómo elegir entre ` qgetenv()` y ` qEnvironmentVariable()`:

CondiciónRecomendación
La variable contiene rutas de archivo o texto introducido por el usuarioqEnvironmentVariable()
Código específico de WindowsqEnvironmentVariable()
Código específico de Unix; la variable de destino no es « QString » y/o se utiliza para interactuar con API ajenas a Qtqgetenv()
La variable de destino es un QStringqEnvironmentVariable()
La variable de destino es un ` QByteArray ` o un `std::string`qgetenv()

Nota: en sistemas Unix, esta función puede provocar pérdida de datos si la cadena original contiene datos binarios arbitrarios que no pueden ser decodificados por el códec de la configuración regional. En ese caso, utilice qgetenv() en su lugar. En Windows, esta función no provoca pérdida de datos.

Nota: el nombre de la variable ` varName ` debe contener únicamente caracteres US-ASCII.

Véase también qputenv(), qgetenv(), qEnvironmentVariableIsSet(), qEnvironmentVariableIsEmpty() y qEnvironmentVariableIntegerValue().

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

Devuelve el valor numérico de la variable de entorno ` varName`. Si ` ok ` no es nulo, establece ` *ok ` en ` true ` o ` false `, dependiendo de si la conversión se ha realizado correctamente.

Equivalente a

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

excepto que es mucho más rápido y no puede lanzar excepciones.

Véase también qgetenv(), qEnvironmentVariable() y qEnvironmentVariableIsSet().

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

Devuelve el valor numérico de la variable de entorno « varName ». Si la variable no está definida o no se ha podido interpretar como un entero, devuelve « std::nullopt ».

Es similar a

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

, salvo que es mucho más rápido y no puede lanzar excepciones.

Si un valor de cero es semánticamente equivalente a una variable vacía o no definida, las aplicaciones pueden utilizar

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

Ten en cuenta que, en este caso, los errores al analizar un valor también producirán un cero.

Pero si un valor cero puede utilizarse para desactivar alguna funcionalidad, las aplicaciones pueden comparar el valor devuelto ` std::optional ` con cero, lo cual solo será cierto si la variable estaba definida y contenía un número que se interpretó como cero, como en:

   bool equals_zero = qEnvironmentVariableIntegerValue(varName) == 0;

Esta función se introdujo en Qt 6.10.

Véase también qgetenv(), qEnvironmentVariable() y qEnvironmentVariableIsSet().

[noexcept] bool qEnvironmentVariableIsEmpty(const char *varName)

Devuelve si la variable de entorno « varName » está vacía.

Equivalente a

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

, salvo que es potencialmente mucho más rápido y no puede lanzar excepciones.

Véase también qgetenv(), qEnvironmentVariable() y qEnvironmentVariableIsSet().

[noexcept] bool qEnvironmentVariableIsSet(const char *varName)

Devuelve si está definida la variable de entorno « varName ».

Equivalente a

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

, salvo que es potencialmente mucho más rápida y no puede lanzar excepciones.

Véase también qgetenv(), qEnvironmentVariable(), qEnvironmentVariableIsEmpty() y qEnvironmentVariableIntegerValue().

QByteArray qgetenv(const char *varName)

Devuelve el valor de la variable de entorno denominada « varName » como un objeto ` QByteArray`. Si no se encuentra ninguna variable con ese nombre en el entorno, esta función devuelve un objeto ` QByteArray` construido por defecto.

Las funciones de manipulación del entorno de Qt son seguras para subprocesos, pero esto requiere que no se llamen directamente a las funciones equivalentes de la biblioteca C, como getenv y putenv.

Para convertir los datos a un ` QString `, utiliza ` QString::fromLocal8Bit()`.

Nota: en Windows de escritorio, qgetenv() puede provocar pérdida de datos si la cadena original contiene caracteres Unicode que no se pueden representar en la codificación ANSI. Utiliza en su lugar qEnvironmentVariable(). En sistemas Unix, esta función no provoca pérdida de datos.

Nota: Esta función es segura para subprocesos.

Véase también qputenv(), qEnvironmentVariable(), qEnvironmentVariableIsSet(), qEnvironmentVariableIsEmpty() y qEnvironmentVariableIntegerValue().

bool qputenv(const char *varName, QByteArrayView value)

Esta función establece el valor de la variable de entorno varName mediante la función value. Creará la variable si no existe. Devuelve 0 si no se ha podido establecer la variable.

Al llamar a `qputenv` con un valor vacío, se elimina la variable de entorno en Windows y se establece (pero vacía) en Unix. Se recomienda utilizar ` qunsetenv()` para obtener un comportamiento totalmente portátil.

Nota: qputenv () se introdujo porque putenv(), de la biblioteca estándar de C, quedó obsoleta en VC2005 (y versiones posteriores). qputenv() utiliza la función de sustitución en VC y llama a la implementación de la biblioteca estándar de C en todas las demás plataformas.

Nota: En las versiones de Qt anteriores a la 6.5, el argumento de ` value ` era ` QByteArray`, no ` QByteArrayView`.

Véase también qgetenv() y qEnvironmentVariable().

bool qunsetenv(const char *varName)

Esta función elimina la variable « varName » del entorno.

Devuelve true si la operación se realiza correctamente.

Véase también qputenv(), qgetenv() y qEnvironmentVariable().

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.