_searchenv_s，_wsearchenv_s

通过使用环境路径搜索文件。 这些版本的 _searchenv、_wsearchenv 具有安全性增强功能，如 CRT 中的安全性功能中所述。

重要

此 API 不能用于在 Windows 运行时中执行的应用程序。 有关详细信息，请参阅通用 Windows 平台应用中不支持的 CRT 函数。

语法

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

参数

filename
要搜索的文件名称。

varname
要搜索的环境。

pathname
用于存储完整路径的缓冲区。

numberOfElements
pathname 缓冲区的大小。

返回值

如果成功，则为零；如果失败，则为错误代码。

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

错误条件

filename	varname	pathname	numberOfElements	返回值	pathname 的内容
任意	任意	NULL	任意	EINVAL	不适用
NULL	any	任意	any	EINVAL	未更改
任意	任意	任意	<= 0	EINVAL	未更改

如果发生这些错误情况中的任何一个，都会调用无效参数处理程序，如参数验证中所述。 如果允许执行继续，则这些功能将 errno 设置为 EINVAL 并返回 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++ 中，使用这些函数由模板重载简化；重载可以自动推导出缓冲区长度 (不再需要指定大小自变量)，并且它们可以自动用以更新、更安全的对应物替换旧的、不安全的函数。 有关详细信息，请参阅安全模板重载。

默认情况下，此函数的全局状态范围限定为应用程序。 若要更改此行为，请参阅 CRT 中的全局状态。

一般文本例程映射

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 );
}

Path for CL.EXE:
C:\Program Files\Microsoft Visual Studio 2010\VC\BIN\CL.EXE

另请参阅

目录控制
_searchenv, _wsearchenv
getenv、_wgetenv
_putenv、_wputenv