getenv_s, _wgetenv_s

從目前的環境取得值。 這些版本的 getenv具有_wgetenv安全性增強功能，如CRT中的安全性功能中所述。

重要

這個 API 不能用於在 Windows 執行階段中執行的應用程式。 如需詳細資訊，請參閱 CRT functions not supported in Universal Windows Platform apps (通用 Windows 平台應用程式中不支援的 CRT 函式)。

語法

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

參數

pReturnValue
所需的緩衝區大小，如果找不到變數，則為 0。

buffer
要儲存環境變數值的緩衝區。

numberOfElements
buffer 的大小。

varname
環境變數名稱。

傳回值

如果成功則為零，否則，如果失敗則為錯誤碼。

錯誤條件

pReturnValue	buffer	numberOfElements	varname	傳回值
NULL	任意	任意	任意	EINVAL
任意	NULL	>0	任意	EINVAL
任意	任意	任意	NULL	EINVAL

上述任何錯誤狀況會叫用無效的參數處理程式，如參數驗證中所述。 若允許繼續執行，函式會將 errno 設定為 EINVAL 並傳回 EINVAL。

此外，如果緩衝區太小，則這些函式會傳回 ERANGE。 它們不會叫用無效的參數處理程式。 它們會在 pReturnValue 寫出所需的緩衝區大小，並藉此使用較大的緩衝區，啟用程式來再次呼叫此函式。

備註

getenv_s 函式會在環境變數清單中搜尋 varname。 getenv_s 在 Windows 作業系統中不區分大小寫。 getenv_s 和 _putenv_s 會使用全域變數 _environ 所指向的環境複本來存取環境。 getenv_s 只會在執行階段程式庫可以存取的資料結構上運作，而不會在作業系統為此處理序所建立的環境「區段」上運作。 因此，使用 envp 自變數的程式 main ，或 wmain 可能會擷取無效的資訊。

_wgetenv_s 是 getenv_s 的寬字元版本，_wgetenv_s 的引數與傳回值是寬字元字串。 _wenviron 全域變數是寬字元版本的 _environ。

在 MBCS 程式中 (例如，在 SBCS ASCII 程式中)，_wenviron 一開始是 NULL，因為此環境由多位元組字元字串所組成。 然後，在第一次呼叫 _wputenv 時，或在第一次呼叫 _wgetenv_s 時，如果 (MBCS) 環境已經存在，則會建立對應的寬字元字串環境，然後再由 _wenviron 指向該變數。

同樣地，在 Unicode (_wmain) 程式中，_environ 一開始是 NULL，因為此環境由寬字元字串所組成。 然後，在第一次呼叫 _putenv 時，或在第一次呼叫 getenv_s 時，如果 (Unicode) 環境已經存在，則會建立對應的 MBCS 環境，然後再由 _environ 指向該變數。

當程式的兩個環境複本同時存在時，執行可能需要較長的時間，因為運行時間系統必須維護這兩個複本。 例如，當您呼叫 _putenv 時，也會自動執行對 _wputenv 的呼叫，使得這兩個環境字串對應。

警告

在罕見情況下，當這個執行階段系統正同時維護此環境的 Unicode 版本和多位元組版本時，這兩個環境版本可能無法完全對應。 這之所以發生，是因為雖然任何唯一的多位元組字元字串會對應到唯一的 Unicode 字串，但從唯一的 Unicode 字串對應到多位元組字元字串並不一定唯一。 如需詳細資訊，請參閱 _environ和 _wenviron。

注意

_putenv_s 和 _getenv_s 系列的函式不是安全執行緒。 當 _putenv_s 正在修改字串時，_getenv_s 可能會傳回此字串的指標，因而導致隨機失敗。 確定這些函式的呼叫已同步。

在 C++ 中，樣板多載簡化了這些函式的使用方式；此多載可自動推斷緩衝區長度，因此不須指定大小引數。 如需詳細資訊，請參閱安全範本多載。

根據預設，此函式的全域狀態會限定於應用程式。 若要變更此行為，請參閱 CRT 中的全域狀態。

一般文字常式對應

TCHAR.H 常式	_UNICODE 和 _MBCS 未定義	_MBCS 已定義	_UNICODE 已定義
_tgetenv_s	getenv_s	getenv_s	_wgetenv_s

若要檢查或變更 TZ 環境變數的值，請視需要使用 getenv_s、_putenv 和 _tzset。 如需 的詳細資訊TZ，請參閱 _tzset 和_daylight 、、 _dstbias_timezone和 _tzname。

需求

常式	必要的標頭
getenv_s	<stdlib.h>
_wgetenv_s	<stdlib.h> 或 <wchar.h>

如需相容性詳細資訊，請參閱相容性。

範例

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

另請參閱

進程和環境控制
環境常數
_putenv, _wputenv
_dupenv_s, _wdupenv_s