Sdílet prostřednictvím

getenv_s, _wgetenv_s

  • Článek

Získá hodnotu z aktuálního prostředí. Tyto verze getenvmají _wgetenv vylepšení zabezpečení, jak je popsáno v funkcích zabezpečení v CRT.

Důležité

Toto rozhraní API nelze použít v aplikacích, které se spouští v prostředí Windows Runtime. Další informace najdete v tématu Funkce CRT, které nejsou v aplikacích Univerzální platforma Windows podporované.

Syntaxe

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

Parametry

pReturnValue
Velikost vyrovnávací paměti, která se vyžaduje, nebo 0, pokud proměnná nebyla nalezena.

buffer
Vyrovnávací paměť pro uložení hodnoty proměnné prostředí.

numberOfElements
Velikost .buffer

varname
Název proměnné prostředí

Vrácená hodnota

Nula v případě úspěchu; jinak kód chyby při selhání.

Chybové podmínky

pReturnValue buffer numberOfElements varname Návratová hodnota
NULL jakékoliv jakékoliv jakékoliv EINVAL
jakékoliv NULL >0 jakékoliv EINVAL
jakékoliv jakékoliv jakékoliv NULL EINVAL

Každá z těchto chybových podmínek vyvolá neplatnou obslužnou rutinu parametru, jak je popsáno v ověření parametru. Pokud je spuštění povoleno pokračovat, funkce nastavené errno na EINVAL a vrátit EINVAL.

Pokud je vyrovnávací paměť příliš malá, vrátí tyto funkce ERANGE. Nevyvolají neplatnou obslužnou rutinu parametru. Zapisují požadovanou velikost vyrovnávací paměti do pReturnValue, a tím umožňují programům volat funkci znovu s větší vyrovnávací pamětí.

Poznámky

Funkce getenv_s vyhledá seznam proměnných varnameprostředí . getenv_s nerozlišuje velká a malá písmena v operačním systému Windows. getenv_s a _putenv_s použijte kopii prostředí, na které odkazuje globální proměnná _environ pro přístup k prostředí. getenv_s funguje pouze v datových strukturách, které jsou přístupné pro knihovnu za běhu, a ne v "segmentu" prostředí vytvořeném pro daný proces operačním systémem. Programy, které používají envp argument nebo main wmain mohou načíst neplatné informace.

_wgetenv_s je verze širokého znaku getenv_s; argument a návratová _wgetenv_s hodnota jsou řetězce širokých znaků. Globální _wenviron proměnná je širokoznační verze _environ.

V programu MBCS (například v programu SBCS ASCII) _wenviron je zpočátku NULL , protože prostředí se skládá z vícebajtových řetězců znaků. Pak se při prvním volání nebo _wputenvpři prvním volání _wgetenv_s, pokud již existuje prostředí (MBCS), vytvoří se odpovídající prostředí řetězce širokého znaku a pak bude odkazovat na _wenviron.

Podobně v programu Unicode (_wmain) je zpočátkuNULL, _environ protože prostředí se skládá z řetězců širokých znaků. Pak se při prvním volání nebo _putenvpři prvním volání getenv_s , pokud již existuje prostředí (Unicode), vytvoří se odpovídající prostředí MBCS a pak odkazuje na _environ.

Pokud v programu existují současně dvě kopie prostředí (MBCS a Unicode), může provádění trvat déle, protože systém za běhu musí udržovat obě kopie. Při volání _putenvse například automaticky spustí volání _wputenv , aby dva řetězce prostředí odpovídaly.

Upozornění

Ve výjimečných případech platí, že když systém za běhu udržuje verzi Unicode i vícebajtovou verzi prostředí, nemusí tyto dvě verze prostředí přesně odpovídat. K tomu dochází proto, že i když se jakýkoli jedinečný řetězec s vícebajtovými znaky mapuje na jedinečný řetězec Unicode, mapování z jedinečného řetězce Unicode na řetězec s vícebajtovými znaky nemusí být nutně jedinečné. Další informace naleznete v tématu _environ, _wenviron.

Poznámka:

Funkce _putenv_s a _getenv_s jejich rodiny nejsou bezpečné pro přístup z více vláken. _getenv_s může vrátit ukazatel řetězce při _putenv_s úpravě řetězce a způsobit tak náhodná selhání. Ujistěte se, že jsou volání těchto funkcí synchronizovaná.

V jazyce C++ je použití těchto funkcí zjednodušeno přetíženími šablon; přetížení mohou odvodit délku vyrovnávací paměti automaticky a tím eliminovat potřebu zadat argument velikosti. Další informace naleznete v tématu Přetížení šablon zabezpečení.

Ve výchozím nastavení je globální stav této funkce vymezen na aplikaci. Chcete-li toto chování změnit, přečtěte si téma Globální stav v CRT.

Mapování rutin obecného textu

TCHAR.H rutina _UNICODE a _MBCS není definován _MBCS definovaný _UNICODE definovaný
_tgetenv_s getenv_s getenv_s _wgetenv_s

Chcete-li zkontrolovat nebo změnit hodnotu TZ proměnné prostředí, použijte getenv_s_putenv, a _tzset, podle potřeby. Další informace o TZ, viz _tzset a_daylight , _dstbias, _timezonea _tzname.

Požadavky

Rutina Požadovaný hlavičkový soubor
getenv_s <stdlib.h>
_wgetenv_s <stdlib.h> nebo <wchar.h>

Další informace o kompatibilitě najdete v tématu Kompatibilita.

Příklad

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

Viz také

Řízení procesů a prostředí
Konstanty prostředí
_putenv, _wputenv
_dupenv_s, _wdupenv_s