getenv_s
, _wgetenv_s
从当前环境中获取值。 这些版本的 getenv
、_wgetenv
具有安全增强功能,如 CRT 中的安全功能中所述。
重要
此 API 不能用于在 Windows 运行时中执行的应用程序。 有关详细信息,请参阅通用 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 |
any | NULL |
>0 | 任意 | EINVAL |
任意 | 任意 | any | NULL |
EINVAL |
如参数验证中所述,这些错误条件调用无效参数处理程序。 如果允许执行继续,则这些函数将 errno
设置为 EINVAL
并返回 EINVAL
。
此外,如果缓冲区太小,这些函数将返回 ERANGE
。 它们不会调用无效的参数处理程序。 它们将在 pReturnValue
中写出所需的缓冲区大小,从而使程序能够使用较大的缓冲区再次调用函数。
备注
getenv_s
函数将搜索 varname
的环境变量列表。 在 Windows 操作系统中,getenv_s
不区分大小写。 getenv_s
和 _putenv_s
使用全局变量 _environ
所指向环境的副本来访问该环境。 getenv_s
只能在可访问运行时库的数据结构上执行,不能在由操作系统对进程创建的环境“段”上执行。 因此,对 main
或 wmain
使用 envp
参数的程序可能会检索无效信息。
_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) 环境已存在,则将由 _environ
创建对应的 MBCS 环境并指向该环境。
当程序的两个环境副本(MBCS 和 Unicode)同时存在时,执行可能需要更长的时间,因为运行时系统必须维护这两个副本。 例如,当调用 _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