getenv_s、_wgetenv_s

發行項
06/09/2015

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

重要

這個應用程式開發介面不能用於 Windows 執行階段中執行的應用程式。如需詳細資訊，請參閱 /ZW 不支援 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	any	any	any	EINVAL
any	NULL	>0	any	EINVAL
any	any	any	NULL	EINVAL

這些錯誤任一叫用無效的參數處理常式，如參數驗證中所述。如果允許繼續執行，這些函式會將 errno 設為 EINVAL，並傳回 EINVAL。

此外，如果緩衝區太小，這些函式會傳回 ERANGE。它們不叫用無效的參數處理常式。它們寫出在 pReturnValue所需的緩衝區大小和讓程式再呼叫函式與較大的緩衝區。

備註

getenv_s 函式會搜尋環境變數名稱的 varname。 Windows 作業系統中 getenv_s 不區分大小寫。 getenv_s 和 _putenv_s 使用環境指向由全域變數 _environ 的複本存取環境。 getenv_s 只能使用在資料結構可供這個執行階段程式庫和由作業系統不在環境「為處理序」建立的區段時使用。因此，使用 envp 引數傳遞至 main 或 wmain 的程式可能會擷取不正確的資訊。

_wgetenv_s 是 getenv_s 的寬字元版本，_wgetenv_s 函式的參數和回傳值是寬字元字串。 _wenviron 全域變數是 _environ的寬字元版本。

在 MBCS 程式 (例如，在 SBCS ASCII)， _wenviron 最初是 NULL 因為環境由多位元組字元字串所組成。接下來，第一次呼叫 _wputenv，或者如果 MBCS 環境已經存在時，則在第一次呼叫 _wgetenv_s ，會建立對應的寬字元字串環境且被 _wenviron 指向。

同樣在 Unicode ((_wmain) 程式， _environ 最初是 NULL ，因為環境由寬字元字串所組成。接下來，第一次呼叫 _putenv，或者如果 MBCS 環境已經存在時，則在第一次呼叫 getenv_s ，會建立對應的寬字元字串環境且被 _environ 指向。

當兩個環境複本 (MBCS 和 Unicode) 時同時存在的程式，這個執行階段系統必須維護兩份複本，造成較慢的執行時間。例如，當您呼叫 _putenv，一個呼叫 _wputenv 的方式也會自動執行，因此，這兩個環境字串對應。

警告

在極少的情況下，當這個 Runtime 系統維護的 Unicode 版本和環境的多位元組版本時，這兩個環境版本可能對應不正確。這是因為雖然任何唯一的多位元組字元字串對應到唯一的 Unicode 字串，從唯一的 Unicode 字串對應到多位元組字元字串不一定是唯一的。如需詳細資訊，請參閱_environ、_wenviron。

注意事項
_putenv_s 和 _getenv_s 函式群不是安全執行緒。當 _putenv_s 修改字串時產生隨機失敗，_getenv_s 會傳回字串指標。確定這些函式的呼叫已同步。

在 C++ 中，這些函式的使用被簡化為使用樣板多載；使用多載可以自動推斷緩衝區的大小而不必在參數中指明大小。如需詳細資訊，請參閱安全範本多載。

一般文字常式對應

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