共用方式為


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

_wgetenv_sgetenv_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