getenv_s, _wgetenv_s

Articolo
06/09/2015

Ottiene un valore dell'ambiente corrente. Queste versioni di getenv, _wgetenv contengono i miglioramenti della sicurezza come descritto in Funzionalità di sicurezza in CRT.

Importante

Questa API non può essere utilizzata nelle applicazioni eseguite in Windows Runtime.Per ulteriori informazioni, vedere Funzioni CRT non supportate 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

Parametri

pReturnValue
La dimensione del buffer richiesta, oppure 0 se la variabile non viene trovata.
buffer
Buffer per archiviare il valore della variabile di ambiente.
numberOfElements
Dimensione del buffer.
varname
Nome della variabile d'ambiente.

Valore restituito

Zero se ha esito positivo; altrimenti, un codice di errore in caso di errore.

Condizioni di errore

pReturnValue	buffer	numberOfElements	varname	Valore restituito
NULL	any	any	any	EINVAL
any	NULL	>0	any	EINVAL
any	any	any	NULL	EINVAL

Alcune di queste condizioni di errore richiamano un gestore di parametro non valido, come descritto in Convalida dei parametri. Se l'esecuzione può continuare, le funzioni impostano errno su EINVAL e restituiscono EINVAL.

Inoltre, se il buffer è troppo piccolo, queste funzioni restituiscono ERANGE. Non invocano un gestore di parametro non valido. Scrivono le dimensioni del buffer richieste in pReturnValue e pertanto consentono ai programmi di chiamare nuovamente la funzione con una dimensione maggiore del buffer.

Note

La funzione getenv_s ricerca l'elenco delle variabili di ambiente per varname. getenv_s non rileva la distinzione tra maiuscole e minuscole nel sistema operativo Windows. getenv_s e _putenv_s usano la copia dell'ambiente puntato dalla variabile globale _environ per accedere all'ambiente. getenv_s funziona solo nelle strutture dati che sono accessibili dalla libreria di runtime e non sul "segmento" dell'ambiente creato per il processo dal sistema operativo. Di conseguenza, i programmi che utilizzano l'argomento envp nel main o nel wmain possono recuperare informazioni non valide.

_wgetenv_s è una versione a caratteri estesi di getenv_s; gli argomenti e i valori restituiti di _wgetenv_s sono stringhe con caratteri estesi. La variabile globale _wenviron è una versione a caratteri estesi di _environ.

In un programma MBCS (ad esempio, in un programma ASCII SBCS), _wenviron inizialmente è NULL perché l'ambiente è costituito da stringhe di caratteri multibyte. Quindi, alla prima chiamata a _wputenv, o alla prima chiamata a _wgetenv_s, se esiste già un ambiente (MBCS), viene creato un corrispondente ambiente di stringhe di caratteri estesi e viene puntato da _wenviron.

Allo stesso modo in un programma Unicode (_wmain, _environ inizialmente è NULL perché l'ambiente è costituito da stringhe di caratteri estesi. Quindi, alla prima chiamata a _putenv, o alla prima chiamata a getenv_s se un ambiente (Unicode) esiste già, un corrispondente ambiente MBCS viene creato e punta a _environ.

Quando due copie dell'ambiente (MBCS e Unicode) sono presenti contemporaneamente in un programma, il sistema runtime deve gestire entrambe le copie, e questo è causa una esecuzione più lenta. Ad esempio, ogni volta che viene chiamato _putenv, viene eseguita automaticamente anche una chiamata a _wputenv così che le due stringhe di ambiente corrispondano.

Avviso

In rare occasioni, quando il sistema runtime gestisce sia una versione Unicode che una versione multibyte dell'ambiente, queste due versioni dell'ambiente potrebbero non corrispondere esattamente.Ciò è dovuto al fatto che, sebbene ogni stringa univoca con caratteri multibyte viene mappata in una stringa Unicode univoca, il mapping da una stringa Unicode univoca a una stringa di caratteri multibyte non è sempre univoco.Per ulteriori informazioni, vedere _environ, _wenviron.

Nota

Le famiglie di funzioni _getenv_s e _putenv_s non sono thread-safe._getenv_s potrebbe restituire un puntatore di stringa mentre _putenv_s sta modificando la stringa, causando errori casuali.Assicurarsi che le chiamate alle funzioni siano sincronizzate.

In C++, l'utilizzo di queste funzioni viene semplificato dagli overload del modello; gli overload possono dedurre la lunghezza del buffer automaticamente, eliminando la necessità di specificare un argomento per la dimensione. Per ulteriori informazioni, vedere Overload di modelli sicuri.

Mapping di routine di testo generico

Routine TCHAR.H	_UNICODE & _MBCS non definiti	_MBCS definito	_UNICODE definito
_tgetenv_s	getenv_s	getenv_s	_wgetenv_s

Per controllare o modificare il valore della variabile d'ambiente TZ, utilizzare getenv_s, _putenv e _tzset come richiesto. Per ulteriori informazioni su TZ, vedere _tzset e _daylight, _dstbias, _timezone, and _tzname.

Requisiti

Routine	Intestazione obbligatoria
getenv_s	<stdlib.h>
_wgetenv_s	<stdlib.h> o <wchar.h>

Per ulteriori informazioni sulla compatibilità, vedere Compatibilità.

Esempio

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