_searchenv_s， _wsearchenv_s

项目
04/10/2013

搜索使用环境路径的文件。这些是 _searchenv，_wsearchenv 的版本与安全增强如 CRT中的安全功能所述。

重要

此 API 不能在运行时的窗口执行的应用程序。有关更多信息，请参见 CRT 函数不支持与 /ZW。

errno_t _searchenv_s(
   const char *filename,
   const char *varname,
   char *pathname,
   size_t numberOfElements
);
errno_t _wsearchenv_s(
   const wchar_t *filename,
   const wchar_t *varname,
   wchar_t *pathname,
   size_t numberOfElements
);
template <size_t size>
errno_t _searchenv_s(
   const char *filename,
   const char *varname,
   char (&pathname)[size]
); // C++ only
template <size_t size>
errno_t _wsearchenv_s(
   const wchar_t *filename,
   const wchar_t *varname,
   wchar_t (&pathname)[size]
); // C++ only

参数

[in] filename
搜索的文件的名称。
[in] varname
搜索的环境。
[out] pathname
存储完整路径的缓冲区。
[in] numberOfElements
pathname缓冲区的大小。

返回值

零，如果成功；在失败的错误代码。

如果 filename 是空字符串，则返回值是 ENOENT。

错误状态

filename	varname	pathname	numberOfElements	返回值	pathname内容
any	any	NULL	any	EINVAL	无
NULL	any	any	any	EINVAL	不更改
any	any	any	<= 0	EINVAL	不更改

如果这些错误以上任一状态出现，无效参数调用处理程序，如参数验证所述。如果执行允许继续，对 EINVAL 的这些功能集 errno 和返回 EINVAL。

备注

_searchenv_s 实例搜索在指定字段的目标文件。 varname 变量可以是指定目录路径列表，例如 PATH、LIB和 INCLUDE的所有环境或用户定义的变量。由于 _searchenv_s 区分大小写，varname 应与环境变量的大小写。如果 varname 不匹配"进程的环境中定义的环境变量的名称，则该函数返回零，而 pathname 变量保持不变。

实例首先搜索在当前工作目录中的文件。如果它没有找到文件，它通过环境变量指定的目录查找下一个。如果目标文件在这些目录之一，新创建的路径复制到 pathname。如果找不到 filename 文件，pathname 包含一个空 null 终止的字符串。

pathname 缓冲区应长度为满足全长的至少 _MAX_PATH 字符构造的路径名。否则，_searchenv_s 可能会超过 pathname 缓冲区导致意外行为。

_wsearchenv_s 是 _searchenv_s的宽字符版本；为 _wsearchenv_s 的参数是宽字符字符串。 _wsearchenv_s 和 _searchenv_s 否则具有相同的行为。

在 C++ 中，使用这些功能由模板超加载简化；超加载可能推断缓冲区长度 (自动不再需要指定范围参数)，并且还可以用以较新，安全重复自动替换旧，不安全的功能。有关更多信息，请参见安全模板重载。

一般文本例程映射

Tchar.h 实例	未定义的_UNICODE 和_MBCS	定义的_MBCS	定义的_UNICODE
_tsearchenv_s	_searchenv_s	_searchenv_s	_wsearchenv_s

要求

实例	必需的标头
_searchenv_s	<stdlib.h>
_wsearchenv_s	<stdlib.h> 或 <wchar.h>

有关更多兼容性信息，请参见中介绍的兼容性。

示例

// crt_searchenv_s.c
/* This program searches for a file in
 * a directory specified by an environment variable.
 */

#include <stdlib.h>
#include <stdio.h>

int main( void )
{
   char pathbuffer[_MAX_PATH];
   char searchfile[] = "CL.EXE";
   char envvar[] = "PATH";
   errno_t err;

   /* Search for file in PATH environment variable: */
   err = _searchenv_s( searchfile, envvar, pathbuffer, _MAX_PATH );
   if (err != 0)
   {
      printf("Error searching the path. Error code: %d\n", err);
   }
   if( *pathbuffer != '\0' )
      printf( "Path for %s:\n%s\n", searchfile, pathbuffer );
   else
      printf( "%s not found\n", searchfile );
}