getenv_s, _wgetenv_s

Article
03/26/2013

Obtient une valeur 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é du CRT.

Important

Cette API ne peut pas être utilisée dans les applications qui s'exécutent dans 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
La taille de mémoire tampon requise, ou 0 si la variable est introuvable.
buffer
Mémoire tampon pour stocker la valeur de la variable d'environnement.
numberOfElements
Taille d' buffer.
varname
Nom de la variable d'environnement.

Valeur de retour

Zéro si l'opération a réussi ; sinon, le code d'erreur en cas de échec.

Conditions d'erreur

pReturnValue	buffer	numberOfElements	varname	Valeur de retour
NULL	any	any	any	EINVAL
any	NULL	>0	any	EINVAL
any	any	any	NULL	EINVAL

L'un de ces conditions d'erreur appelle un gestionnaire de paramètre non valide, comme décrit dans Validation des paramètres.Si est autorisé à l'exécution pour continuer, errno défini par fonctions à EINVAL et à EINVALde retour.

En outre, si la mémoire tampon est trop petite, ces fonctions ERANGEde retour.Ils n'appellent pas de gestionnaire de paramètre non valide.Ils écrivent la taille de mémoire tampon requise dans pReturnValue, et permettent ainsi aux programmes d'appeler la fonction de nouveau avec une plus grande mémoire tampon.

Notes

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

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

Dans un programme MBCS (par exemple, dans un programme ASCII SBCS), _wenviron est initialement NULL parce que l'environnement est composé des chaînes de caractères multioctets.Puis, dans le premier appel à _wputenv, ou dans le premier appel à _wgetenv_s, si un environnement (MBCS) existe déjà, un environnement correspondant de chaîne à caractères larges est créé puis est globale pointe vers _wenviron.

De la même façon dans un programme Unicode (_wmain), _environ est initialement NULL parce que l'environnement est composé des chaînes à caractères larges.Puis, dans le premier appel à _putenv, ou dans le premier appel à getenv_s si l'environnement (Unicode) existe déjà, un environnement correspondant MBCS est créé puis est globale pointe vers _environ.

Lorsque deux copies de l'environnement (MBCS et Unicode) existent simultanément dans un programme, le système runtime doit mettre à jour les deux copies, et cela provoque une durée d'exécution plus lente.Par exemple, lorsque vous appelez _putenv, un appel à _wputenv est également exécuté automatiquement afin que les deux chaînes d'environnement correspondant.

Attention
Dans des instances rares, lorsque le système runtime gère une version Unicode et une version multioctets de l'environnement, les deux versions d'environnement peuvent ne pas correspondre exactement.Cela se produit parce que, bien qu'aucune seule mappage de chaîne de caractères multioctets à une seule chaîne Unicode, le mappage d'une seule chaîne Unicode d'une chaîne de caractères multioctets ne soit nécessairement seule.Pour plus d'informations, consultez _environ, _wenviron.

Dans des instances rares, lorsque le système runtime gère une version Unicode et une version multioctets de l'environnement, les deux versions d'environnement peuvent ne pas correspondre exactement.Cela se produit parce que, bien qu'aucune seule mappage de chaîne de caractères multioctets à une seule chaîne Unicode, le mappage d'une seule chaîne Unicode d'une chaîne de caractères multioctets ne soit nécessairement seule.Pour plus d'informations, consultez _environ, _wenviron.

[!REMARQUE]

Les familles de _putenv_s et d' _getenv_s des fonctions ne sont pas thread-safe._getenv_s peut retourner un pointeur de chaîne alors qu' _putenv_s modifie les échecs aléatoires de chaîne et ainsi de cause.Assurez-vous que les appels à ces fonctions sont synchronisés.

En C++, l'utilisation de ces fonctions est simplifiée par des surcharges de modèle ; les surcharges peuvent également déduire la longueur de la mémoire tampon automatiquement et éviter ainsi le besoin de spécifier un argument de taille.Pour plus d'informations, consultez Surcharges sécurisées de modèle.

Mappages de routines de texte générique

Routine de TCHAR.H	_UNICODE et non définis _MBCS	_MBCS défini	_UNICODE défini
_tgetenv_s	getenv_s	getenv_s	_wgetenv_s

Pour vérifier ou modifier la valeur de la variable d'environnement d' TZ, de l'utilisation getenv_s, de l' _putenv, et de l' _tzset, si nécessaire.Pour plus d'informations sur TZ, consultez _tzset et _daylight, _dstbias, _timezone, et _tzname.

Configuration requise

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

Pour des informations de compatibilité supplémentaires, consultez Compatibilité.

Exemple

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