getenv_s, _wgetenv_s

Artykuł
06/09/2015

Pobiera wartość z bieżącym środowisku.Te wersje getenv, _wgetenv mieć rozszerzenia zabezpieczeń opisane w Funkcje zabezpieczeń w CRT.

Ważne
Ten interfejs API nie można używać w aplikacji, których wykonywanie w Środowisko wykonawcze systemu Windows.Aby uzyskać więcej informacji, zobacz CRT funkcje nie obsługiwane przez /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
Rozmiar buforu, co jest wymagane, lub 0, jeśli zmienna nie zostanie znaleziony.
buffer
Bufor do przechowywania wartości zmiennej środowiskowej.
numberOfElements
Size of buffer.
varname
Nazwa zmiennej środowiskowej.

Wartość zwracana

Zero, jeśli kończy się pomyślnie; w przeciwnym razie błąd kodu w przypadku awarii.

Warunki błędów

pReturnValue	buffer	numberOfElements	varname	Zwracana wartość
NULL	wszelkie	wszelkie	wszelkie	EINVAL
wszelkie	NULL	> 0	wszelkie	EINVAL
wszelkie	wszelkie	wszelkie	NULL	EINVAL

Jeden z następujących warunków błąd wywołuje funkcję obsługi nieprawidłowy parametr, zgodnie z opisem w Sprawdzanie poprawności parametru.Jeśli wykonanie może kontynuować, zestaw funkcji errno do EINVAL i powrót EINVAL.

Ponadto, jeśli bufor jest za mały, funkcje te zwracają ERANGE.One nie wywoływać funkcję obsługi nieprawidłowy parametr.Zapisują się wymagany rozmiar buforu w pReturnValuei tym samym zapewnić programy, aby wywołać funkcję ponownie z większy bufor.

Uwagi

getenv_s Funkcja przeszukuje listę zmiennych środowiskowych dla varname.getenv_snie jest uwzględniana wielkość liter, w systemie operacyjnym Windows.getenv_si _putenv_s używanie kopii jest wskazywany przez zmienną globalnego środowiska _environ aby uzyskiwać dostęp do środowiska.getenv_sdziała tylko na struktur danych, które są dostępne dla biblioteki uruchomieniowej, a nie na środowisko naturalne "segment", który jest tworzony dla procesu przez system operacyjny.W związku z tym, programy używające envp argument główne lub wmain może pobierać nieprawidłowe informacje.

_wgetenv_sjest ona szerokich znaków do getenv_s; wartość argumentów i _wgetenv_s są ciągami szerokich znaków._wenviron Zmienna globalna jest ona szerokich znaków do _environ.

W programie MBCS (na przykład w programie SBCS ASCII) _wenviron jest początkowo NULL ponieważ środowiska składa się z ciągów znaków wielobajtowych.Następnie na pierwszym wywołaniu _wputenv, lub na pierwsze wezwanie do _wgetenv_s, jeśli środowisku (MBCS) już istnieje, odpowiedniego środowiska dla łańcucha szerokich znaków jest tworzony i następnie jest wskazywana przez _wenviron.

Podobnie w Unicode (_wmain) program, _environ jest początkowo NULL ponieważ środowiska składa się z ciągów szerokich znaków.Następnie na pierwszym wywołaniu _putenv, lub na pierwsze wezwanie do getenv_s po środowisku (Unicode) już istnieje, odpowiednie środowisko MBCS zostanie utworzona i następnie jest wskazywana przez _environ.

Gdy dwie kopie środowiska (MBCS Unicode) istnieją jednocześnie w programie, system wykonawczy muszą utrzymywać obie kopie i powoduje wolniejsze czas wykonania.Na przykład, gdy wywołanie _putenv, wywołanie _wputenv jest również wykonywane automatycznie tak, aby odpowiadać ciągów środowiskowych dwa.

Przestroga
W rzadkich przypadkach gdy system wykonawczy jest utrzymanie zarówno wersję Unicode, jak i wielobajtowych wersją środowiska naturalnego, w wersjach środowiska dwóch mogą nie odpowiadać dokładnie.Dzieje się tak, ponieważ mimo, że dowolny unikatowy ciąg znaków wielobajtowych mapowany na unikatowy ciąg Unicode, mapowanie unikatowy ciąg Unicode na ciąg znaków wielobajtowych nie jest koniecznie unikatowa.Aby uzyskać więcej informacji, zobacz _environ, _wenviron.

W rzadkich przypadkach gdy system wykonawczy jest utrzymanie zarówno wersję Unicode, jak i wielobajtowych wersją środowiska naturalnego, w wersjach środowiska dwóch mogą nie odpowiadać dokładnie.Dzieje się tak, ponieważ mimo, że dowolny unikatowy ciąg znaków wielobajtowych mapowany na unikatowy ciąg Unicode, mapowanie unikatowy ciąg Unicode na ciąg znaków wielobajtowych nie jest koniecznie unikatowa.Aby uzyskać więcej informacji, zobacz _environ, _wenviron.

[!UWAGA]

_putenv_s i _getenv_s rodziny funkcji nie są wątków._getenv_smógł zwrócić wskaźnik ciąg podczas _putenv_s modyfikuje ciąg i tym samym być przyczyną błędów losowych.Upewnij się, że wywołania tych funkcji są synchronizowane.

W języku C++ korzystanie z tych funkcji jest uproszczony przez przeciążenia szablonu; overloads można automatycznie rozpoznać długość buforu, a tym samym eliminują potrzebę określono argument rozmiar.Aby uzyskać więcej informacji, zobacz Przeciążenia bezpiecznych szablonów.

Tekst rodzajowy rutynowych mapowania

TCHAR.Rozpoczęto wykonywanie procedury h	_UNICODE & _MBCS nie zdefiniowany	_MBCS, definicja	_UNICODE, definicja
_tgetenv_s	getenv_s	getenv_s	_wgetenv_s

Aby sprawdzić lub zmienić wartość TZ użycie zmiennej, środowiska getenv_s, _putenv, i _tzset, stosownie do potrzeb.Aby uzyskać więcej informacji o TZ, zobacz _tzset i _daylight, _dstbias, _timezone, i _tzname.

Wymagania

Rozpoczęto wykonywanie procedury	Wymaganego nagłówka
getenv_s	<stdlib.h>
_wgetenv_s	<stdlib.h> lub <wchar.h>

Aby uzyskać dodatkowe informacje o zgodności, zobacz Zgodność.

Przykład

// 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);
}