Udostępnij za pośrednictwem

getenv_s, _wgetenv_s

  • Artykuł

Pobiera wartość z bieżącego środowiska. Te wersje programu getenv _wgetenvmają ulepszenia zabezpieczeń zgodnie z opisem w temacie Funkcje zabezpieczeń w narzędziu CRT.

Ważne

Tego interfejsu API nie można używać w aplikacjach wykonywanych w środowisko wykonawcze systemu Windows. Aby uzyskać więcej informacji, zobacz Funkcje CRT nieobsługiwane w aplikacjach platforma uniwersalna systemu Windows.

Składnia

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
Wymagany rozmiar buforu lub 0, jeśli zmienna nie zostanie znaleziona.

buffer
Bufor do przechowywania wartości zmiennej środowiskowej.

numberOfElements
bufferRozmiar .

varname
Nazwa zmiennej środowiskowej.

Wartość zwracana

Zero w przypadku powodzenia; w przeciwnym razie kod błędu dotyczący błędu.

Warunki błędu

pReturnValue buffer numberOfElements varname Wartość zwracana
NULL dowolny dowolny dowolny EINVAL
dowolny NULL >0 dowolny EINVAL
dowolny dowolny dowolny NULL EINVAL

Każdy z tych warunków błędu wywołuje nieprawidłową procedurę obsługi parametrów, zgodnie z opisem w temacie Weryfikacja parametrów. Jeśli wykonywanie jest dozwolone do kontynuowania, funkcje ustawione errno na EINVAL i zwracają wartość EINVAL.

Ponadto jeśli bufor jest za mały, te funkcje zwracają wartość ERANGE. Nie wywołują nieprawidłowej procedury obsługi parametrów. Zapisują wymagany rozmiar buforu w pReturnValuepliku , a tym samym umożliwiają programom ponowne wywołanie funkcji z większym buforem.

Uwagi

Funkcja getenv_s wyszukuje listę zmiennych środowiskowych dla varnameelementu . getenv_s nie uwzględnia wielkości liter w systemie operacyjnym Windows. getenv_s i _putenv_s użyj kopii środowiska wskazywanego przez zmienną globalną _environ w celu uzyskania dostępu do środowiska. getenv_s działa tylko w strukturach danych, które są dostępne dla biblioteki czasu wykonywania, a nie w środowisku "segment", który jest tworzony dla procesu przez system operacyjny. W związku z tym programy używające argumentu envp do main lub wmain mogą pobierać nieprawidłowe informacje.

_wgetenv_s jest wersją szerokoznakową ; getenv_sargument i wartość zwracana _wgetenv_s są ciągami o szerokim znaku. Zmienna _wenviron globalna jest wersją o szerokim znaku _environ.

W programie MBCS (na przykład w programie SBCS ASCII) _wenviron początkowo NULL środowisko składa się z ciągów wielobajtowych znaków. Następnie przy pierwszym wywołaniu metody _wputenvlub przy pierwszym wywołaniu do _wgetenv_sprogramu , jeśli środowisko (MBCS) już istnieje, zostanie utworzone odpowiednie środowisko ciągów o szerokim znaku, a następnie jest wskazywane przez _wenviron.

Podobnie w programie _environ Unicode (_wmain) początkowo środowisko NULL składa się z ciągów wieloznakowych. Następnie przy pierwszym wywołaniu metody _putenvlub przy pierwszym wywołaniu do getenv_s środowiska (Unicode) jest już tworzone odpowiednie środowisko MBCS, a następnie jest wskazywane przez _environ.

Gdy w programie istnieją jednocześnie dwie kopie środowiska (MBCS i Unicode), wykonanie może trwać dłużej, ponieważ system czasu wykonywania musi obsługiwać obie kopie. Na przykład po wywołaniu _putenvmetody wywołanie _wputenv metody jest również wykonywane automatycznie, tak aby dwa ciągi środowiska odpowiadały.

Uwaga

W rzadkich przypadkach, gdy system czasu wykonywania utrzymuje zarówno wersję Unicode, jak i wielobajtową wersję środowiska, te dwie wersje środowiska mogą nie odpowiadać dokładnie. Dzieje się tak, ponieważ chociaż każdy unikatowy ciąg wielobajtowy mapuje na unikatowy ciąg Unicode, mapowanie z unikatowego ciągu Unicode na ciąg znaków wielobajtowych nie musi być unikatowe. Aby uzyskać więcej informacji, zobacz _environ, _wenviron.

Uwaga

Rodziny _putenv_s funkcji i _getenv_s nie są bezpieczne wątkowo. _getenv_s może zwrócić wskaźnik ciągu podczas _putenv_s modyfikowania ciągu, a tym samym powodować losowe błędy. Upewnij się, że wywołania tych funkcji są zsynchronizowane.

W języku C++użycie tych funkcji jest uproszczone przez przeciążenia szablonów; przeciążenia mogą automatycznie wnioskować długość buforu, a tym samym wyeliminować konieczność określenia argumentu rozmiaru. Aby uzyskać więcej informacji, zobacz Bezpieczne przeciążenia szablonów.

Domyślnie stan globalny tej funkcji jest zakresem aplikacji. Aby zmienić to zachowanie, zobacz Stan globalny w CRT.

Mapowania procedur tekstu ogólnego

TCHAR.H rutyna _UNICODE i _MBCS niezdefiniowane _MBCS zdefiniowany _UNICODE zdefiniowany
_tgetenv_s getenv_s getenv_s _wgetenv_s

Aby sprawdzić lub zmienić wartość zmiennej środowiskowej TZ , użyj wartości getenv_s, _putenvi _tzset, zgodnie z potrzebami. Aby uzyskać więcej informacji na temat TZ, zobacz _tzset i_daylight , _dstbias, _timezonei _tzname.

Wymagania

Procedura Wymagany nagłówek
getenv_s <stdlib.h>
_wgetenv_s <stdlib.h> lub <wchar.h>

Aby uzyskać więcej informacji 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);
}

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

Zobacz też

Kontrola procesu i środowiska
Stałe środowiskowe
_putenv, _wputenv
_dupenv_s, _wdupenv_s