getenv_s, _wgetenv_s

Ottiene un valore dall'ambiente corrente. Queste versioni di hanno _wgetenvmiglioramenti pergetenv la sicurezza, come descritto in Funzionalità di sicurezza in CRT.

Importante

Non è possibile usare questa API nelle applicazioni eseguite in Windows Runtime. Per altre informazioni, vedere Funzioni CRT non supportate nelle app della piattaforma UWP (Universal Windows Platform).

Sintassi

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
Dimensioni del buffer necessarie o 0 se la variabile non viene trovata.

buffer
Buffer per archiviare il valore della variabile di ambiente.

numberOfElements
Dimensioni di buffer.

varname
Nome della variabile di ambiente.

Valore restituito

Zero in caso di esito positivo; in caso contrario un codice di errore.

Condizioni di errore

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

Una di queste condizioni di errore richiama un gestore di parametri non validi, 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 richiamano un gestore di parametri non validi. Scrivono le dimensioni del buffer necessarie in pReturnValue e pertanto consentono ai programmi di chiamare nuovamente la funzione con una dimensione maggiore del buffer.

Osservazioni:

La funzione getenv_s cerca varname nell'elenco delle variabili di ambiente. getenv_s non fa distinzione tra maiuscole e minuscole nel sistema operativo Windows. getenv_s e _putenv_s usano la copia dell'ambiente a cui punta la variabile globale _environ per accedere all'ambiente. getenv_s funziona solo nelle strutture dati che hanno accesso alla libreria di runtime e non sul "segmento" dell'ambiente creato per il processo dal sistema operativo. Pertanto, i programmi che utilizzano l'argomento envp per main o wmain potrebbero recuperare informazioni non valide.

_wgetenv_s è una versione a caratteri wide di getenv_s. L'argomento e il valore restituito di _wgetenv_s sono stringhe a caratteri wide. La variabile globale _wenviron è una versione a caratteri wide 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 un ambiente (MBCS) esiste già, un ambiente di stringhe di caratteri wide corrispondente viene creato e a cui quindi punta _wenviron.

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

Quando due copie dell'ambiente (MBCS e Unicode) esistono simultaneamente in un programma, l'esecuzione può richiedere più tempo, perché il sistema di runtime deve maincontenere entrambe le copie. Ad esempio, quando viene chiamato _putenv, viene eseguita automaticamente una chiamata anche a _wputenv, in modo che le due stringhe dell'ambiente corrispondano.

Attenzione

In rari casi, quando il sistema di runtime riguarda mainsia una versione Unicode che una versione multibyte dell'ambiente, le 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 altre informazioni, vedere _environe _wenviron.

Nota

Le famiglie di funzioni _putenv_s e _getenv_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 di modello; gli overload possono dedurre la lunghezza del buffer automaticamente eliminando la necessità di specificare un argomento per la dimensione. Per altre informazioni, vedere Proteggere gli overload dei modelli.

Per impostazione predefinita, lo stato globale di questa funzione è limitato all'applicazione. Per modificare questo comportamento, vedere Stato globale in CRT.

Mapping di routine di testo generico

TCHAR.H Routine	_UNICODE e _MBCS non definito	_MBCS Definito	_UNICODE Definito
_tgetenv_s	getenv_s	getenv_s	_wgetenv_s

Per controllare o modificare il valore della variabile di ambiente TZ, usare getenv_s, _putenv e _tzset, in base alle esigenze. Per altre informazioni su TZ, vedere _tzset e _daylight, _dstbias, _timezonee _tzname.

Requisiti

Ciclo	Intestazione obbligatoria
getenv_s	<stdlib.h>
_wgetenv_s	<stdlib.h> oppure <wchar.h>

Per altre informazioni sulla compatibilità, vedere Compatibility (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);
}

Original LIB variable is: c:\vctools\lib;c:\vctools\atlmfc\lib;c:\vctools\PlatformSDK\lib;c:\vctools\Visual Studio SDKs\DIA Sdk\lib;c:\vctools\Visual Studio SDKs\BSC Sdk\lib
New LIB variable is: c:\mylib;c:\yourlib

Vedi anche

Processo e controllo dell'ambiente
Costanti ambientali
_putenv, _wputenv
_dupenv_s, _wdupenv_s