getenv_s, _wgetenv_s

Article
06/09/2015

Obtient le à partir de l'environnement de design. Ces versions getenv, _wgetenv présentent des améliorations de sécurité, comme décrit dans Fonctionnalités de sécurité dans le CRT.

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
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 du buffer.
varname
nom de la variable d'environnement

Valeur de retour

Zéro si l'opération a réussi ; un 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'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 définissent errno avec la valeur EINVAL et retournent EINVAL.

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

Notes

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 auquel la variable globale _environ pointe pour accéder à l'environnement. getenv_s fonctionne uniquement sur les structures de données accessibles à la bibliothèque Runtime et non sur le "segment" d'environnement créé pour le processus par le système d'exploitation. Par conséquent, les programmes qui utilisent l'argument envp pour main ou wmain peuvent récupérer 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 de caractères larges. La variable globale _wenviron est une version à caractère élargi de _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. Ensuite, au premier appel de _wputenv, ou de _wgetenv_s si un environnement (MBCS) existe déjà, l'environnement de chaîne à caractère élargi correspondant est créé, et _wenviron pointe vers lui.

De même dans un programme Unicode ((_wmain), _environ est initialement NULL parce que l'environnement est composé des chaînes à caractère élargi. Ensuite, au premier appel de _putenv, ou de getenv_s si un environnement (Unicode) existe déjà, un environnement MBCS correspondant est créé, et _environ pointe vers lui.

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

Avertissement

Dans quelques cas rares, lorsque le système runtime conserve une version Unicode et une version multioctets de l'environnement, ces versions de deux environnements peuvent ne pas correspondre exactement.En effet, bien que toute chaîne multioctets mappe à une seule chaîne Unicode, le mappage d'une seule chaîne Unicode en une chaîne de caractères multioctets n'est pas nécessairement unique.Pour plus d'informations, consultez _environ, _wenviron.

Notes

Les familles de fonctions _putenv_s et _getenv_s ne sont pas sécurisées du point de vue du thread._getenv_s peut retourner un pointeur de chaîne alors que _putenv_s modifie la chaîne, provoquant des défaillances aléatoires.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, en éliminant le besoin de spécifier un argument de taille. Pour plus d'informations, consultez Sécuriser les surcharges de modèle.

Mappages de routines de texte générique

Routine TCHAR.H	_UNICODE & _MBCS non définis	_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 TZ, utilisez getenv_s, _putenv et l'_tzset selon les besoins. Pour plus d'informations sur TZ, consultez _tzset et _daylight, _dstbias, _timezone, and _tzname.

Configuration requise

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

Pour plus d'informations sur la compatibilité, 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);
}