getenv_s _wgetenv_s

Článek
03/26/2013

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

Důležité
Toto rozhraní API nelze použít v aplikacích, které jsou spuštěny v Windows Runtime.Další informace naleznete v tématu CRT funkce nejsou podporovány s /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

Parametry

pReturnValue
Velikost vyrovnávací paměti, který je požadovaný nebo 0, pokud proměnná nebyla nalezena.
buffer
Chcete-li vyrovnávací paměť pro ukládání hodnot proměnné prostředí.
numberOfElements
Size of buffer.
varname
Název proměnné prostředí.

Vrácená hodnota

Nula v případě úspěchu; v opačném případě chybu kód při selhání.

Chybové stavy

pReturnValue	buffer	numberOfElements	varname	Vrácená hodnota
NULL	všechny	všechny	všechny	EINVAL
všechny	NULL	> 0	všechny	EINVAL
všechny	všechny	všechny	NULL	EINVAL

Některé z těchto chybových podmínek vyvolá obslužnou rutinu neplatný parametr, jak je popsáno v Ověření parametrů.Je-li pokračovat, je povoleno zpracování, funkce set errno na EINVAL a vrátit se EINVAL.

Také, pokud je vyrovnávací paměť příliš malá, vrátí tyto funkce ERANGE.Mohou vyvolat obslužnou rutinu neplatný parametr.Jejich zapsání velikost použité vyrovnávací paměti v pReturnValuea tím umožňují programům pro volání funkce s větší vyrovnávací paměť.

Poznámky

getenv_s Funkce prohledá seznam proměnných prostředí pro varname.getenv_sje malá a velká písmena v operačním systému Windows.getenv_sa _putenv_s pomocí kopie prostředí, které se odkazuje globální proměnnou _environ přístup k prostředí.getenv_sfunguje pouze u datových struktur, které jsou k dispozici knihovna run-time a nikoli na životní prostředí "segment", který je vytvořen pro proces operačním systémem.Proto programech, které používají envp argument hlavní nebo wmain může načíst neplatné informace.

_wgetenv_sje verzí širokého znaku getenv_s; argument a vrací hodnotu _wgetenv_s jsou řetězci širokého znaku._wenviron Globální proměnná je verzí širokého znaku _environ.

V programu znakové sady MBCS (například v programu SBCS ASCII) _wenviron je původně NULL protože prostředí je tvořeno vícebajtové znakové řetězce.Poté na první volání _wputenv, nebo při prvním volání _wgetenv_s, je-li prostředí (znaková sada MBCS) již existuje, odpovídající prostředí-široký znak je vytvořen a je potom odkazuje _wenviron.

Podobně v Unicode (_wmain) programu, _environ je původně NULL protože prostředí se skládá z řetězce širokého znaku.Poté na první volání _putenv, nebo při prvním volání getenv_s (Unicode) prostředí již existuje-li, odpovídající znakové sady MBCS prostředí je vytvořena a je potom odkazuje _environ.

Pokud dvě kopie prostředí (znaková sada MBCS a Unicode) současně v programu, běhu systému musí udržovat obě kopie a to má za následek pomalejší doba spuštění.Například při volání _putenv, volání _wputenv se rovněž provádí automaticky tak, že odpovídají prostředí dva řetězce.

Upozornění
Ve výjimečných případech při běhu systému udržuje verze Unicode a vícebajtovou verzí prostředí, verze dvou prostředí nemusí odpovídat přesně.Tato situace nastane, protože ačkoliv libovolný jedinečný řetězec vícebajtových znaků mapuje jedinečný řetězec znaků Unicode, mapování jedinečný řetězec znaků Unicode řetězec vícebajtových znaků není nutně jedinečný.Další informace naleznete v tématu _environ _wenviron.

Ve výjimečných případech při běhu systému udržuje verze Unicode a vícebajtovou verzí prostředí, verze dvou prostředí nemusí odpovídat přesně.Tato situace nastane, protože ačkoliv libovolný jedinečný řetězec vícebajtových znaků mapuje jedinečný řetězec znaků Unicode, mapování jedinečný řetězec znaků Unicode řetězec vícebajtových znaků není nutně jedinečný.Další informace naleznete v tématu _environ _wenviron.

[!POZNÁMKA]

_putenv_s a _getenv_s rodin funkcí jsou vláknově bezpečné._getenv_smůže vrátit ukazatel na řetězec při _putenv_s je úprava řetězce a tím způsobit náhodné selhání.Ujistěte se, že volání na tyto funkce jsou synchronizovány.

V jazyce C++ použití těchto funkcí je zjednodušeno díky přetížení šablony; přetížení můžete odvodit vyrovnávací paměti automaticky a tím eliminovat potřebu určit velikost argumentu.Další informace naleznete v tématu Přetížení šablony zabezpečení.

Mapování rutiny obecného textu

TCHAR.Byla zahájena rutina h	_UNICODE & _MBCS není definováno	_MBCS, definice	_UNICODE definována
_tgetenv_s	getenv_s	getenv_s	_wgetenv_s

Chcete-li zkontrolovat nebo změnit hodnotu TZ proměnné, použijte prostředí getenv_s, _putenv, a _tzset, jak je požadováno.Další informace o TZ, viz _tzset a _daylight, _dstbias, _timezone a _tzname.

Požadavky

Byla zahájena rutina	Požadované záhlaví
getenv_s	<stdlib.h>
_wgetenv_s	<stdlib.h> nebo <wchar.h>

Další informace o kompatibilitě, viz 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);
}