getenv_s, _wgetenv_s

Obtiene un valor del entorno actual. Estas versiones de getenv, _wgetenv tienen mejoras de seguridad, como se describe en Características de seguridad de CRT.

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 de búfer que se requiere, o 0 si la variable no se encuentra.

• buffer
  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 correctamente; si no, un código de error del error.

Condiciones de error

Cualquiera de estas condiciones de error se invoca un controlador no válido de parámetro, tal y 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 ERANGEreturn. No se invoca un controlador no válido del parámetro. Establece el tamaño de búfer en tipo necesario en pReturnValue, y por tanto permiten a los programas para llamar a la función de nuevo 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 utilizan la copia del entorno que se está indicada por la variable global _environ para tener acceso al entorno. getenv_s sólo funciona en estructuras de datos que son accesibles a la biblioteca en tiempo de ejecución y no en el entorno “segmento” que se crea para el proceso por el sistema operativo. Por consiguiente, los programas que utilizan el argumento de envp a principal o a wmain puede recuperar la 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. A continuación, en la primera llamada a _wputenv, o en la primera llamada a _wgetenv_s, si existe un entorno (MBCS) ya, un entorno correspondiente de cadena de caracteres es creado y después indicada por _wenviron.

De igual forma en un programa de Unicode (_wmain), _environ inicialmente es NULL porque el entorno se compone de las cadenas de caracteres. 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 dos copias del entorno (MBCS y Unicode) simultáneamente en un programa, el sistema de runtime debe mantener ambas copias, y esto provoca un runtime más lento. Por ejemplo, cuando se llama a _putenv, una llamada a _wputenv también se ejecuta automáticamente de modo que las dos cadenas de entorno corresponden.

En C++, el uso de estas funciones es simplificado con sobrecargas de plantilla; las sobrecargas pueden deducir longitud de búfer automáticamente y por tanto eliminar la necesidad de especificar un argumento size. Para obtener más información, vea Sobrecargas de plantilla seguras.

Asignaciones de rutina de texto genérico

Para comprobar o cambiar el valor de la variable de entorno TZ , utilice getenv_s, de _putenv, y de _tzset, según sea necesario. Para obtener más información acerca de TZ, vea _tzset y _daylight, _dstbias, _timezone y _tzname.

Requisitos

Para obtener información adicional de compatibilidad, vea 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);
}

Equivalente en .NET Framework

System::Environment::GetEnvironmentVariable

Vea también

Referencia

Control de proceso y de entorno

Constantes de entorno

_putenv, _wputenv

_dupenv_s, _wdupenv_s