getenv_s, _wgetenv_s

 

Pour obtenir la dernière documentation sur Visual Studio 2017, consultez Documentation Visual Studio 2017.

Obtient une valeur à partir de l'environnement actuel. Ces versions de getenv, _wgetenv ont des améliorations de sécurité, comme décrit dans fonctionnalités de sécurité de la bibliothèque CRT.

System_CAPS_ICON_important.jpg Important

Cette API ne peut pas être utilisée dans les applications qui s'exécutent dans le Windows Runtime. Pour plus d’informations, consultez Fonctions CRT non prises en charge avec /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  

Paramètres

pReturnValue
Taille de mémoire tampon nécessaire ou 0 si la variable est introuvable.

buffer
Mémoire tampon chargée de stocker la valeur de la variable d'environnement.

numberOfElements
Taille de la buffer.

varname
Nom de la variable d'environnement.

Zéro en cas de réussite ; code d'erreur en cas d'échec.

Conditions d’erreur

pReturnValuebuffernumberOfElementsvarnameValeur de retour
NULLanyanyanyEINVAL
anyNULL>0anyEINVAL
anyanyanyNULLEINVAL

Une de ces conditions d’erreur appelle un gestionnaire de paramètre non valide, comme décrit dans Validation de paramètre. Si l'exécution est autorisée à se poursuivre, les fonctions affectent à errno la valeur EINVAL et retournent EINVAL.

De même, si la mémoire tampon est trop petite, ces fonctions retournent ERANGE. Elles n'appellent pas de gestionnaire de paramètres non valides. Elles écrivent la taille de mémoire tampon nécessaire dans pReturnValue et permettent ainsi aux programmes de rappeler la fonction avec une mémoire tampon plus grande.

La fonction getenv_s recherche varname dans la liste des variables d'environnement. getenv_s ne respecte pas la casse dans le système d'exploitation Windows. getenv_s et _putenv_s utilisent la copie de l'environnement vers laquelle pointe la variable globale _environ pour accéder à l'environnement. getenv_s fonctionne uniquement sur les structures de données accessibles à la bibliothèque Runtime et non sur l'environnement « segment » que crée le système d'exploitation pour le processus. Par conséquent, les programmes qui utilisent la envp l’argument de principal ou wmain peut extraire des informations non valides.

_wgetenv_s est une version à caractères larges de getenv_s ; l'argument et la valeur de retour de _wgetenv_s sont des chaînes à caractères larges. La variable globale _wenviron est une version à caractères larges de _environ.

Dans un programme MBCS (par exemple, un programme ASCII SBSC), la valeur initiale de _wenviron est NULL, car l'environnement se compose de chaînes de caractères multioctets. Ensuite, au premier appel à _wputenv ou _wgetenv_s, s'il existe déjà un environnement (MBCS), un environnement à chaînes de caractères larges correspondant est créé, puis désigné par _wenviron.

De la même manière, dans un programme Unicode (_wmain), la valeur initiale de _environ est NULL, car l'environnement se compose de chaînes de caractères larges. Ensuite, au premier appel à _putenv ou getenv_s, s'il existe déjà un environnement (Unicode), un environnement MBCS correspondant est créé, puis désigné par _environ.

Quand il existe simultanément deux copies de l'environnement (MBCS et Unicode) dans un programme, le système Runtime doit gérer les deux copies, ce qui ralentit les temps d'exécution. Par exemple, quand vous appelez _putenv, un appel à _wputenv est aussi exécutée automatiquement, de sorte que les deux chaînes d'environnement correspondent.

System_CAPS_ICON_caution.jpg Attention

Dans de rares cas, quand le système Runtime gère une version Unicode et une version multioctet de l'environnement, il se peut que les deux versions d'environnement ne correspondent pas exactement. En effet, même si une chaîne de caractères multioctets unique est mappée à une chaîne Unicode unique, le mappage d'une chaîne Unicode unique à une chaîne de caractères multioctets n'est pas nécessairement unique. Pour plus d’informations, consultez _environ, _wenviron.

System_CAPS_ICON_note.jpg Remarque

Les familles de fonctions _putenv_s et _getenv_s ne sont pas thread-safe. _getenv_s peut retourner un pointeur de chaîne pendant que _putenv_s modifie la chaîne, ce qui provoque par voie de conséquence des échecs aléatoires. Assurez-vous que les appels à ces fonctions sont synchronisés.

En C++, l’utilisation de ces fonctions est simplifiée par les surcharges de modèle ; les surcharges peuvent déduire automatiquement la longueur de la mémoire tampon, ce qui évite ainsi d’avoir à spécifier un argument de taille. Pour plus d'informations, consultez Secure Template Overloads.

Mappages de routines de texte générique

Routine TCHAR.H_UNICODE et _MBCS non définis_MBCS défini_UNICODE défini
_tgetenv_sgetenv_sgetenv_s_wgetenv_s

Pour vérifier ou modifier la valeur de la variable d'environnement TZ, utilisez getenv_s, _putenv et _tzset, selon les besoins. Pour plus d’informations sur TZ, consultez _tzset et _daylight, _dstbias, _timezone et _tzname.

RoutineEn-tête requis
getenv_s<stdlib.h>
_wgetenv_s<stdlib.h> ou <wchar.h>

Pour plus d'informations sur la compatibilité, voir Compatibilité.

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

Processus de contrôle et d’environnement
Constantes d’environnement
_putenv, _wputenv
_dupenv_s, _wdupenv_s

Afficher: