getenv_s, _wgetenv_sgetenv_s, _wgetenv_s

Ottiene un valore dall'ambiente corrente.Gets a value from the current environment. Queste versioni di getenv, _wgetenv includono miglioramenti per la sicurezza, come descritto in Funzionalità di sicurezza in CRT.These versions of getenv, _wgetenv have security enhancements, as described in Security Features in the CRT.

Importante

Non è possibile usare questa API nelle applicazioni eseguite in Windows Runtime.This API cannot be used in applications that execute in the Windows Runtime. Per altre informazioni, vedere Funzioni CRT non supportate nelle app della piattaforma UWP (Universal Windows Platform).For more information, see CRT functions not supported in Universal Windows Platform apps.

SintassiSyntax

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

ParametriParameters

pReturnValuepReturnValue
La dimensione del buffer richiesta oppure 0 se la variabile non viene trovata.The buffer size that's required, or 0 if the variable is not found.

bufferbuffer
Buffer per archiviare il valore della variabile di ambiente.Buffer to store the value of the environment variable.

numberOfElementsnumberOfElements
Dimensioni del buffer.Size of buffer.

varnamevarname
Nome della variabile di ambiente.Environment variable name.

Valore restituitoReturn Value

Zero in caso di esito positivo; in caso contrario un codice di errore.Zero if successful; otherwise, an error code on failure.

Condizioni di erroreError Conditions

pReturnValuepReturnValue bufferbuffer numberOfElementsnumberOfElements varnamevarname Valore restituitoReturn Value
NULLNULL qualsiasiany qualsiasiany qualsiasiany EINVALEINVAL
qualsiasiany NULLNULL >0>0 qualsiasiany EINVALEINVAL
qualsiasiany qualsiasiany qualsiasiany NULLNULL EINVALEINVAL

Alcune di queste condizioni di errore richiamano un gestore di parametri non validi, come descritto in Convalida dei parametri.Any of these error conditions invokes an invalid parameter handler, as described in Parameter Validation. Se l'esecuzione può continuare, le funzioni impostano errno alla EINVAL e restituire EINVAL.If execution is allowed to continue, the functions set errno to EINVAL and return EINVAL.

Inoltre, se il buffer è troppo piccolo, queste funzioni restituiscono ERANGE.Also, if the buffer is too small, these functions return ERANGE. Non invocano un gestore di parametro non valido.They do not invoke an invalid parameter handler. Scrivono le dimensioni del buffer necessarie in pReturnValuee pertanto consentono ai programmi chiamare la funzione con un buffer più grande.They write out the required buffer size in pReturnValue, and thereby enable programs to call the function again with a larger buffer.

NoteRemarks

Il getenv_s funzione Cerca nell'elenco delle variabili di ambiente per varname.The getenv_s function searches the list of environment variables for varname. getenv_s non distinzione maiuscole / minuscole nel sistema operativo Windows.getenv_s is not case sensitive in the Windows operating system. getenv_s e putenv_s usano la copia dell'ambiente a cui viene fatto riferimento tramite la variabile globale Environ per accedere all'ambiente.getenv_s and _putenv_s use the copy of the environment that's pointed to by the global variable _environ to access the environment. getenv_s funziona solo nelle strutture dati che sono accessibili per la libreria run-time e non sul "segmento" che viene creato per il processo dal sistema operativo dell'ambiente.getenv_s operates only on the data structures that are accessible to the run-time library and not on the environment "segment" that's created for the process by the operating system. Pertanto, i programmi che usano il envp argomento principale o wmain possono recuperare informazioni non valide.Therefore, programs that use the envp argument to main or wmain might retrieve invalid information.

wgetenv_s è una versione a caratteri wide getenv_s; l'argomento e il valore restituito di wgetenv_s sono stringhe a caratteri "wide"._wgetenv_s is a wide-character version of getenv_s; the argument and return value of _wgetenv_s are wide-character strings. Il wenviron (variabile globale) è una versione a caratteri "wide" Environ.The _wenviron global variable is a wide-character version of _environ.

In un programma MBCS (ad esempio, in un programma ASCII SBCS), wenviron inizialmente NULL perché l'ambiente è costituito da stringhe di caratteri multibyte.In an MBCS program (for example, in an SBCS ASCII program), _wenviron is initially NULL because the environment is composed of multibyte-character strings. Quindi, alla prima chiamata a wputenv, o alla prima chiamata a wgetenv_s, se esiste già un ambiente (MBCS), un ambiente di stringa di caratteri wide corrispondente viene creato e quindi punta a wenviron.Then, on the first call to _wputenv, or on the first call to _wgetenv_s, if an (MBCS) environment already exists, a corresponding wide-character string environment is created and is then pointed to by _wenviron.

Allo stesso modo in un formato Unicode (_wmain), programma Environ inizialmente NULL perché l'ambiente è costituito da stringhe di caratteri "wide".Similarly in a Unicode (_wmain) program, _environ is initially NULL because the environment is composed of wide-character strings. Quindi, alla prima chiamata a putenv, o alla prima chiamata a getenv_s se esiste già un ambiente (Unicode), un ambiente MBCS corrispondente viene creato e quindi a cui punta _ Environ.Then, on the first call to _putenv, or on the first call to getenv_s if a (Unicode) environment already exists, a corresponding MBCS environment is created and is then pointed to by _environ.

Quando due copie dell'ambiente (MBCS e Unicode) sono presenti contemporaneamente in un programma, il sistema runtime deve gestire entrambe le copie, con conseguente esecuzione più lenta.When two copies of the environment (MBCS and Unicode) exist simultaneously in a program, the run-time system must maintain both copies, and this causes slower execution time. Ad esempio, quando si chiama putenv, una chiamata a wputenv anche viene eseguita automaticamente in modo che le due stringhe dell'ambiente corrispondano.For example, when you call _putenv, a call to _wputenv is also executed automatically so that the two environment strings correspond.

Attenzione

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.In rare instances, when the run-time system is maintaining both a Unicode version and a multibyte version of the environment, the two environment versions may not correspond exactly. 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.This happens because, although any unique multibyte-character string maps to a unique Unicode string, the mapping from a unique Unicode string to a multibyte-character string is not necessarily unique. Per altre informazioni, vedere _environ, _wenviron.For more information, see _environ, _wenviron.

Nota

Il putenv_s e _getenv_s famiglie di funzioni non sono thread-safe.The _putenv_s and _getenv_s families of functions are not thread-safe. _getenv_s potrebbe restituire un puntatore di stringa mentre putenv_s sta modificando la stringa, causando errori casuali._getenv_s could return a string pointer while _putenv_s is modifying the string and thereby cause random failures. Assicurarsi che le chiamate alle funzioni siano sincronizzate.Make sure that calls to these functions are synchronized.

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.In C++, use of these functions is simplified by template overloads; the overloads can infer buffer length automatically and thereby eliminate the need to specify a size argument. Per altre informazioni, vedere Overload di modelli sicuri.For more information, see Secure Template Overloads.

Mapping di routine di testo genericoGeneric-Text Routine Mappings

Routine TCHAR.HTCHAR.H routine _UNICODE e _MBCS non definiti_UNICODE & _MBCS not defined _MBCS definito_MBCS defined _UNICODE definito_UNICODE defined
tgetenv_s_tgetenv_s getenv_sgetenv_s getenv_sgetenv_s _wgetenv_s_wgetenv_s

Per controllare o modificare il valore di TZ uso delle variabili, ambiente getenv_s, putenv, e tzsetcome richiesto.To check or change the value of the TZ environment variable, use getenv_s, _putenv, and _tzset, as required. Per ulteriori informazioni TZ, vedere tzset e Daylight, _dstbias, TimeZone e tzname.For more information about TZ, see _tzset and _daylight, _dstbias, _timezone, and _tzname.

RequisitiRequirements

RoutineRoutine Intestazione obbligatoriaRequired header
getenv_sgetenv_s <stdlib.h><stdlib.h>
_wgetenv_s_wgetenv_s <stdlib.h> or <wchar.h><stdlib.h> or <wchar.h>

Per altre informazioni sulla compatibilità, vedere Compatibilità.For additional compatibility information, see Compatibility.

EsempioExample

// 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

Vedere ancheSee also

Controllo di processi e ambienteProcess and Environment Control
Costanti di ambienteEnvironmental Constants
_putenv, _wputenv_putenv, _wputenv
_dupenv_s, _wdupenv_s_dupenv_s, _wdupenv_s