Partager via


getenv_s, _wgetenv_s

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.

Mise en gardeAttention

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

Équivalent .NET Framework

System::Environment::GetEnvironmentVariable

Voir aussi

Référence

Processus et contrôle ambiance

Constantes d'environnement

_putenv, _wputenv

_dupenv_s, _wdupenv_s