getenv_s、_wgetenv_s
从当前环境获取值。 getenv、_wgetenv 的这些版本如 CRT 中的安全功能 所述,其安全得到了增强。
重要
此 API 不能用于在 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。 getenv_s 在Windows操作系统下不区分大小写。 getenv_s 和 _putenv_s 使用环境的副本用全局变量指向该 _environ 访问该环境。 getenv_s 仅对数据结构可以访问运行库和不在环境“进程”操作系统创建的段。 因此,使用 envp 参数。main 或 wmain 的程序可以检索无效信息。
_wsetlocale_wgetenv_s 是 getenv_s 的宽字符版本,_wgetenv_s 参数和 的返回值都是宽字符字符串。 _wenviron 全局变量是 _environ的宽字符版本。
在 MBCS 程序 (例如,在 SBCS ASCII 程序),_wenviron 最初是 NULL,因为环境由多字节字符字符串组成。 然后,首次调用 _wputenv 或在 MBCS 环境已存在的情况下首次调用 _wgetenv_s 时,将创建相应的宽字符字符串环境,并由_wenviron指向。
同样在 Unicode ((_wmain) 程序,_environ 最初是 NULL,因为环境由宽字符字符串组成。 首次调用 _putenv, 或首次调用 getenv_s如果一个 (Unicode) 环境已经存在,一个对应的环境被创建然后由 _environ指向。
当环境的两个副本 (MBCS 和 Unicode) 时同时存在于程序,运行时系统必须保留两个副本,导致较慢的执行时间。 例如,只要调用 _putenv,对 _wputenv 的调用也会自动执行,因此,两个环境字符串对应。
警告
在极少数情况下,当该运行时系统维护一个 Unicode 版本和该环境中的某个多字节版本,这两个环境版本可能无法正确对应。这是因为任何单个多字节字符字符串映射到单个 Unicode 字符串,从单个 Unicode 字符串到多字节字符字符串不一定是唯一的。有关详细信息,请参阅_environ、_wenviron。
备注
_putenv_s 和 _getenv_s函数系列不是线程安全的。_getenv_s 可以返回字符串指针,当 _putenv_s 修改该字符串时,会导致随机崩溃。确保对这些函数的调用同步。
在 C++ 中,使用这些函数是由重载模板简化;该重载可以自动推断缓冲区长度,而无需指定范围参数。 有关更多信息,请参见安全模板重载。
一般文本例程映射
TCHAR.H 例程 |
_UNICODE & _MBCS not defined |
已定义 _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);
}
.NET Framework 等效项
System::Environment::GetEnvironmentVariable