getenv_s, _wgetenv_s

Articolo
03/26/2013

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

Importante
Questa API non può essere utilizzato 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
Le dimensioni del buffer richieste, 0 o se la variabile non trovata.
buffer
Buffer per archiviare il valore della variabile.
numberOfElements
Dimensione di buffer.
varname
Nome della variabile di ambiente.

Valore restituito

Zero se ha esito positivo; in caso contrario, 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

Queste condizioni di errore viene richiamato un gestore non valido di parametro, come descritto in Convalida dei parametri.Se l'esecuzione è consentita per continuare, errno impostato funzioni a EINVAL e a EINVALrestituita.

Inoltre, se il buffer è troppo piccolo, queste funzioni ERANGErestituita.Non include un gestore non valido di parametro.Scrivere le dimensioni del buffer richieste in pReturnValuee pertanto consente ai programmi per chiamare nuovamente la funzione con un buffer più grande.

Note

La funzione di getenv_s trovare l'elenco di variabili di ambiente varname.getenv_s non viene rilevata la distinzione tra maiuscole e minuscole nel sistema operativo Windows.getenv_s e _putenv_s utilizzano la copia dell'ambiente che si fa riferimento la variabile globale _environ per accedere all'ambiente.getenv_s funziona solo in strutture di dati che sono accessibili alla libreria di runtime e non sull'ambiente "segmento" creato per il processo dal sistema operativo.Di conseguenza, i programmi che utilizzano l'argomento di envp a principale o a wmain possono recuperare le 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 di _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 di stringhe di caratteri multibyte.Successivamente, nella prima chiamata a _wputenv, o alla prima chiamata a _wgetenv_s, se un ambiente MBCS) esiste già, un ambiente corrispondente stringa di caratteri estesi viene creato e si fa riferimento da _wenviron.

Analogamente a un programma di (_wmainUnicode), _environ inizialmente è NULL perché l'ambiente è costituito di stringhe di caratteri estesi.Successivamente, nella prima chiamata a _putenv, o alla prima chiamata a getenv_s se l'ambiente (Unicode) esiste già, un ambiente corrispondente MBCS viene creato e si fa riferimento da _environ.

Quando due copie dell'ambiente MBCS e Unicode) presenti contemporaneamente in un programma, il sistema runtime deve gestire entrambe le copie e viene generato il tempo di esecuzione più lenta.Ad esempio, quando si chiama _putenv, una chiamata a _wputenv viene eseguita automaticamente in modo che le due stringhe dell'ambiente corrispondano.

Attenzione
In rare occasioni, quando il sistema in runtime viene gestito sia una versione Unicode che una versione multibyteambiente, le due versioni dell'ambiente non possono corrispondere esattamente.Ciò accade perché, anche se alcuni mapping univoci della stringa con caratteri multibyte a una stringa Unicode univoca, il mapping da una stringa Unicode univoca a una stringa di caratteri multibyte non è sempre univoci.Per ulteriori informazioni, vedere _environ, _wenviron.

In rare occasioni, quando il sistema in runtime viene gestito sia una versione Unicode che una versione multibyteambiente, le due versioni dell'ambiente non possono corrispondere esattamente.Ciò accade perché, anche se alcuni mapping univoci della stringa con caratteri multibyte a una stringa Unicode univoca, il mapping da una stringa Unicode univoca a una stringa di caratteri multibyte non è sempre univoci.Per ulteriori informazioni, vedere _environ, _wenviron.

[!NOTA]

I gruppi di _getenv_s e di _putenv_s di funzioni non sono thread-safe._getenv_s potrebbe restituire un puntatore di stringa mentre _putenv_s sta modificando gli errori casuali causa della stringa e.Assicurarsi che le chiamate alle funzioni siano sincronizzate.

In C++, l'utilizzo di queste funzioni è semplificato dagli overload del modello; gli overload possono dedurre la lunghezza del buffer automaticamente e quindi eliminare la necessità di specificare un argomento di dimensione.Per ulteriori informazioni, vedere Assicurarsi che gli overload del modello.

Mapping di routine a Testo generico

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

Per verificare o modificare il valore della variabile di ambiente TZ, utilizzare getenv_s, di _putenve di _tzset, come richiesto.Per ulteriori informazioni su TZ, vedere _tzset e _daylight, _dstbias, _timezone e _tzname.

Requisiti

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

Per informazioni aggiuntive di 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);
}