getenv_s, _wgetenv_s
Obtiene un valor del entorno actual. Estas versiones de , _wgetenvtienen mejoras degetenv seguridad, como se describe en Características de seguridad de CRT.
Importante
Esta API no se puede usar en aplicaciones que se ejecutan en Windows en tiempo de ejecución. Para obtener más información, vea Funciones de CRT no admitidas en aplicaciones de la Plataforma universal de Windows.
Sintaxis
errno_t getenv_s(
size_t *pReturnValue,
char* buffer,
size_t numberOfElements,
const char *varname
);
errno_t _wgetenv_s(
size_t *pReturnValue,
wchar_t *buffer,
size_t numberOfElements,
const wchar_t *varname
);
template <size_t size>
errno_t getenv_s(
size_t *pReturnValue,
char (&buffer)[size],
const char *varname
); // C++ only
template <size_t size>
errno_t _wgetenv_s(
size_t *pReturnValue,
wchar_t (&buffer)[size],
const wchar_t *varname
); // C++ only
Parámetros
pReturnValue
El tamaño del búfer necesario, o 0 si no se encuentra la variable.
buffer
El búfer para almacenar el valor de la variable de entorno.
numberOfElements
Tamaño de buffer.
varname
Nombre de la variable de entorno.
Valor devuelto
Cero si es correcto; en caso contrario, un código de error si se produce un error.
Condiciones del error
pReturnValue |
buffer |
numberOfElements |
varname |
Valor devuelto |
|---|---|---|---|---|
NULL |
cualquiera | cualquiera | cualquiera | EINVAL |
| cualquiera | NULL |
>0 | cualquiera | EINVAL |
| cualquiera | cualquiera | cualquiera | NULL |
EINVAL |
Cualquiera de estas condiciones de error invoca un controlador de parámetros no válidos, como se describe en Validación de parámetros. Si la ejecución puede continuar, las funciones establecen errno en EINVAL y devuelven EINVAL.
Además, si el búfer es demasiado pequeño, estas funciones devuelven ERANGE. No invocan un controlador de parámetros no válido. Escriben el tamaño de búfer necesario en pReturnValue y, de esta forma, permite a los programas llamar a la función con un búfer mayor.
Comentarios
La función getenv_s busca varname en la lista de variables de entorno. getenv_s no distingue entre mayúsculas y minúsculas en el sistema operativo Windows. getenv_s y _putenv_s usan la copia del entorno indicada por la variable global _environ para tener acceso al entorno. getenv_s solo funciona en las estructuras de datos a las que puede tener acceso la biblioteca en tiempo de ejecución y no en el “segmento” del entorno que el sistema operativo crea para el proceso. En consecuencia, los programas que usan el argumento envp en main o wmain podrían recuperar información no válida.
_wgetenv_s es una versión con caracteres anchos de getenv_s; el argumento y el valor devuelto de _wgetenv_s son cadenas de caracteres anchos. La variable global _wenviron es una versión con caracteres anchos de _environ.
En un programa de MBCS (por ejemplo, en un programa ASCII de SBCS), _wenviron es inicialmente NULL porque el entorno está formado por cadenas de caracteres multibyte. Después, en la primera llamada a _wputenv, o en la primera llamada a _wgetenv_s, si ya existe un entorno (MBCS), se crea un entorno de cadenas de caracteres anchos correspondiente, al que señala _wenviron.
De la misma forma, en un programa de Unicode (_wmain), _environ es inicialmente NULL porque el entorno está formado por cadenas de caracteres anchos. Después, en la primera llamada a _putenv, o en la primera llamada a getenv_s si ya existe un entorno (Unicode), se crea un entorno de MBCS correspondiente, al que señala _environ.
Cuando existen dos copias del entorno (MBCS y Unicode) simultáneamente en un programa, la ejecución puede tardar más, ya que el sistema en tiempo de ejecución debe mantener ambas copias. Por ejemplo, cuando se llame a _putenv, se ejecuta automáticamente una llamada a _wputenv, de forma que se correspondan las dos cadenas de entorno.
Precaución
En raras ocasiones, cuando el sistema en tiempo de ejecución mantiene una versión Unicode y una versión multibyte del entorno, las dos versiones del entorno podrían no corresponderse exactamente. La razón es que, aunque cualquier cadena de caracteres multibyte se asigna a una cadena de Unicode única, la asignación de una cadena de Unicode única a una cadena de caracteres multibyte no es necesariamente única. Para más información, vea _environ, _wenviron.
Nota:
Los grupos de funciones de _putenv_s y _getenv_s no son seguros para subprocesos. _getenv_s podría devolver un puntero de cadena mientras _putenv_s modifica la cadena y, por lo tanto, generarían errores aleatorios. Asegúrese de que las llamadas a estas funciones están sincronizadas.
En C++, el uso de estas funciones se simplifica mediante sobrecargas de plantilla. Las sobrecargas pueden deducir automáticamente la longitud del búfer, lo que elimina la necesidad de especificar un argumento de tamaño. Para obtener más información, consulte Sobrecargas de plantilla seguras.
De manera predeterminada, el estado global de esta función está limitado a la aplicación. Para cambiar este comportamiento, consulte Estado global en CRT.
Asignaciones de rutinas de texto genérico
Rutina TCHAR.H |
_UNICODE y _MBCS no definidos |
_MBCS definido |
_UNICODE definido |
|---|---|---|---|
_tgetenv_s |
getenv_s |
getenv_s |
_wgetenv_s |
Para comprobar o cambiar el valor de la variable de entorno TZ, use getenv_s, _putenv y _tzset según sea necesario. Para más información sobre TZ, consulte _tzset y _daylight, _dstbias, _timezone y _tzname.
Requisitos
| Routine | Encabezado necesario |
|---|---|
getenv_s |
<stdlib.h> |
_wgetenv_s |
<stdlib.h> o <wchar.h> |
Para obtener más información sobre compatibilidad, consulte Compatibilidad.
Ejemplo
// crt_getenv_s.c
// This program uses getenv_s to retrieve
// the LIB environment variable and then uses
// _putenv to change it to a new value.
#include <stdlib.h>
#include <stdio.h>
int main( void )
{
char* libvar;
size_t requiredSize;
getenv_s( &requiredSize, NULL, 0, "LIB");
if (requiredSize == 0)
{
printf("LIB doesn't exist!\n");
exit(1);
}
libvar = (char*) malloc(requiredSize * sizeof(char));
if (!libvar)
{
printf("Failed to allocate memory!\n");
exit(1);
}
// Get the value of the LIB environment variable.
getenv_s( &requiredSize, libvar, requiredSize, "LIB" );
printf( "Original LIB variable is: %s\n", libvar );
// Attempt to change path. Note that this only affects
// the environment variable of the current process. The command
// processor's environment is not changed.
_putenv_s( "LIB", "c:\\mylib;c:\\yourlib" );
getenv_s( &requiredSize, NULL, 0, "LIB");
libvar = (char*) realloc(libvar, requiredSize * sizeof(char));
if (!libvar)
{
printf("Failed to allocate memory!\n");
exit(1);
}
// Get the new value of the LIB environment variable.
getenv_s( &requiredSize, libvar, requiredSize, "LIB" );
printf( "New LIB variable is: %s\n", libvar );
free(libvar);
}
Original LIB variable is: c:\vctools\lib;c:\vctools\atlmfc\lib;c:\vctools\PlatformSDK\lib;c:\vctools\Visual Studio SDKs\DIA Sdk\lib;c:\vctools\Visual Studio SDKs\BSC Sdk\lib
New LIB variable is: c:\mylib;c:\yourlib
Vea también
Control de procesos y entornos
Constantes de entorno
_putenv, _wputenv
_dupenv_s, _wdupenv_s