Se recomienda usar Visual Studio 2017

getenv_s, _wgetenv_s

 

Para obtener la documentación más reciente de Visual Studio 2017 RC, consulte Documentación de Visual Studio 2017 RC.

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.

System_CAPS_ICON_important.jpg Importante

Esta API no se puede usar en aplicaciones que se ejecutan en Windows en tiempo de ejecución. Para 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 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.

Cero si es correcto; en caso contrario, un código de error si se produce un error.

Condiciones de error

pReturnValuebuffernumberOfElementsvarnameValor devuelto
NULLcualquieracualquieracualquieraEINVAL
cualquieraNULL>0cualquieraEINVAL
cualquieracualquieracualquieraNULLEINVAL

Cualquiera de estas condiciones de error invoca un controlador de parámetros no válidos, como se describe en validación del parámetro. 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.

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. Por lo tanto, los programas que utilizan el envp argumento principal o wmain podría 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.

Si dos copias del entorno (MBCS y Unicode) existen simultáneamente en un programa, el sistema en tiempo de ejecución debe mantener las dos copias, lo que ralentiza el tiempo de ejecución. 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.

System_CAPS_ICON_caution.jpg 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 obtener más información, consulte _environ, _wenviron.

System_CAPS_ICON_note.jpg 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, consulta Secure Template Overloads.

Asignaciones de rutina de texto genérico

Rutina TCHAR.H_UNICODE y _MBCS no definidos_MBCS definido_UNICODE definido
_tgetenv_sgetenv_sgetenv_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 obtener más información acerca de TZ, consulte _tzset y _daylight, _dstbias, _timezone y _tzname.

RutinaEncabezado necesario
getenv_s<stdlib.h>
_wgetenv_s<stdlib.h> o <wchar.h>

Para obtener más información sobre compatibilidad, vea Compatibilidad.

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

System::Environment::GetEnvironmentVariable

Control de proceso y entorno
Constantes de entorno
_putenv, _wputenv
_dupenv_s, _wdupenv_s

Mostrar: