getenv_s _wgetenv_s

發行項
03/26/2013

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

重要

這個應用程式開發介面無法用來在 Windows 執行階段中執行的應用程式。如需詳細資訊，請參閱 CRT 函式不支援使用 /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

參數

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

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

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

備註

getenv_s 函式會搜尋環境變數名稱的 varname。 getenv_s 不區分大小寫的 Windows 作業系統中。 getenv_s 和 _putenv_s 使用指向由全域變數 _environ 存取執行環境的複本。 getenv_s 在能夠存取這個執行階段程式庫和不在環境「區段」為處理序建立由作業系統的資料結構只能使用。因此，使用 envp 引數傳遞至主要或 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。

當兩個環境複本 (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);
}