_searchenv、_wsearchenv_searchenv, _wsearchenv

使用环境路径搜索文件。Uses environment paths to search for a file. 提供这些函数的更多安全版本;请参阅 _searchenv_s、_wsearchenv_sMore secure versions of these functions are available; see _searchenv_s, _wsearchenv_s.

重要

此 API 不能用于在 Windows 运行时中执行的应用程序。This API cannot be used in applications that execute in the Windows Runtime. 有关详细信息,请参阅通用 Windows 平台应用中不支持的 CRT 函数For more information, see CRT functions not supported in Universal Windows Platform apps.

语法Syntax

void _searchenv(
   const char *filename,
   const char *varname,
   char *pathname
);
void _wsearchenv(
   const wchar_t *filename,
   const wchar_t *varname,
   wchar_t *pathname
);
template <size_t size>
void _searchenv(
   const char *filename,
   const char *varname,
   char (&pathname)[size]
); // C++ only
template <size_t size>
void _wsearchenv(
   const wchar_t *filename,
   const wchar_t *varname,
   wchar_t (&pathname)[size]
); // C++ only

参数Parameters

filename要搜索的文件的名称。filename Name of the file to search for.

varname要搜索的环境。varname Environment to search.

路径名用于存储的完整路径缓冲区。pathname Buffer to store the complete path.

备注Remarks

_Searchenv例程搜索指定的域中的目标文件。The _searchenv routine searches for the target file in the specified domain. Varname变量可以是任何环境或用户定义变量 — 例如,路径LIB,或包括-,它指定目录路径的列表。The varname variable can be any environment or user-defined variable—for example, PATH, LIB, or INCLUDE—that specifies a list of directory paths. 因为 _searchenv区分大小写, varname应匹配的环境变量的大小写。Because _searchenv is case-sensitive, varname should match the case of the environment variable.

例程首先搜索当前工作目录中的文件。The routine first searches for the file in the current working directory. 如果找不到文件,它将查找由环境变量指定的目录。If it does not find the file, it looks through the directories that are specified by the environment variable. 如果目标文件在其中一个目录,则新创建的路径复制到路径名If the target file is in one of those directories, the newly created path is copied into pathname. 如果filename找不到文件,路径名包含一个空的以 null 结尾的字符串。If the filename file is not found, pathname contains an empty null-terminated string.

路径名缓冲区至少应为 _MAX_PATH长度个字符,以便容纳构建的路径名称的完整长度。The pathname buffer should be at least _MAX_PATH characters long to accommodate the full length of the constructed path name. 否则为 _searchenv可能溢出路径名缓冲并导致意外的行为。Otherwise, _searchenv might overrun the pathname buffer and cause unexpected behavior.

_wsearchenv是宽字符版本的 _searchenv,和的自变量 _wsearchenv是宽字符字符串。_wsearchenv is a wide-character version of _searchenv, and the arguments to _wsearchenv are wide-character strings. _wsearchenv_searchenv否则具有相同行为。_wsearchenv and _searchenv behave identically otherwise.

如果filename为空字符串,这些函数将返回ENOENTIf filename is an empty string, these functions return ENOENT.

如果filename路径名NULL指针,无效参数处理程序调用中所述,参数验证If filename or pathname is a NULL pointer, the invalid parameter handler is invoked, as described in Parameter Validation. 如果允许执行继续,则这些函数将返回-1 并设置errnoEINVALIf execution is allowed to continue, these functions return -1 and set errno to EINVAL.

有关详细信息errno和错误代码,请参阅errno 常量For more information about errno and error codes, see errno Constants.

在 C++ 中,这些函数具有可调用这些函数的更新、更安全的版本的模板重载。In C++, these functions have template overloads that invoke the newer, more secure counterparts of these functions. 有关详细信息,请参阅 Secure Template OverloadsFor more information, see Secure Template Overloads.

一般文本例程映射Generic-Text Routine Mappings

Tchar.h 例程Tchar.h routine 未定义 _UNICODE 和 _MBCS_UNICODE and _MBCS not defined 已定义 _MBCS_MBCS defined 已定义 _UNICODE_UNICODE defined
_tsearchenv_tsearchenv _searchenv_searchenv _searchenv_searchenv _wsearchenv_wsearchenv

要求Requirements

例程Routine 必需的标头Required header
_searchenv_searchenv <stdlib.h><stdlib.h>
_wsearchenv_wsearchenv <stdlib.h> 或 <wchar.h><stdlib.h> or <wchar.h>

有关更多兼容性信息,请参阅 兼容性For more compatibility information, see Compatibility.

示例Example

// crt_searchenv.c
// compile with: /W3
// This program searches for a file in
// a directory that's 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";

   // Search for file in PATH environment variable:
   _searchenv( searchfile, envvar, pathbuffer ); // C4996
   // Note: _searchenv is deprecated; consider using _searchenv_s
   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 8\VC\BIN\CL.EXE

请参阅See also

目录控制Directory Control
getenv、_wgetenvgetenv, _wgetenv
_putenv、_wputenv_putenv, _wputenv
_searchenv_s、_wsearchenv_s_searchenv_s, _wsearchenv_s