getenv_s, _wgetenv_s

Artículo
06/09/2015

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.

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 con /ZW.

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

pReturnValue	buffer	numberOfElements	varname	Valor devuelto
NULL	any	any	any	EINVAL
any	NULL	>0	any	EINVAL
any	any	any	NULL	EINVAL

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.

Advertencia

Son raros, cuando el sistema en tiempo de ejecución mantiene una versión Unicode y una versión multibyte de entorno, las dos versiones del entorno pueden no corresponda exactamente.Esto sucede porque, aunque ninguna mapas única de la cadena de multibyte- carácter en una cadena Unicode única, la asignación de una cadena Unicode única de una cadena de multibyte- carácter no es necesariamente única.Para obtener 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 está modificando los errores aleatorios de la cadena y por tanto de la causa.Asegúrese de que las llamadas a estas funciones están sincronizadas.

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

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 , 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

Rutina	Encabezado necesario
getenv_s	<stdlib.h>
_wgetenv_s	<stdlib.h> o <wchar.h>

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);
}