getenv_s， _wgetenv_s

项目
04/10/2013

从当前环境获取值。getenv， _wgetenv 的这些版本具有安全增强功能，如 CRT中的安全功能所述。

重要事项
此 API 不能在 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 的功能集 errno 和返回 EINVAL。

此外，如果缓冲区太小，这些函数返回 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 的调用也会自动执行，以便两个环境字符串对应。

警告
在极少数情况下，那么，当该运行时系统维护一个 Unicode 版本和该环境中的某个多字节版本，两个环境版本可能无法正确对应。发生这种情况，因为，不过，任何单个多字节字符字符串映射到单个 Unicode 字符串，从单个 Unicode 字符串到多字节字符字符串不一定是唯一的。有关更多信息，请参见_environ， _wenviron。

在极少数情况下，那么，当该运行时系统维护一个 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);
}