_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.


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  


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

要搜索的环境。Environment to search.

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


_searchenv 例程搜索指定域中的目标文件。The _searchenv routine searches for the target file in the specified domain. varname 变量可以是指定目录路径的列表的任何环境或用户定义的变量(例如,PATHLIBINCLUDE)。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. 如果目标文件在其中一个目录中,则新创建的路径将被复制到 pathname 中。If the target file is in one of those directories, the newly created path is copied into pathname. 如果找不到 filename 文件,pathname 将包含一个以 null 值结束的空字符串。If the filename file is not found, pathname contains an empty null-terminated string.

pathname 缓冲区的字符长度至少应为 _MAX_PATH,以便容纳构建的路径名称的完整长度。The pathname buffer should be at least _MAX_PATH characters long to accommodate the full length of the constructed path name. 否则,_searchenv 可能溢出 pathname 缓冲并导致意外行为。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.

如果 filenamepathnameNULL 指针,则调用无效的参数处理程序,如参数验证中所述。If filename or pathname is a NULL pointer, the invalid parameter handler is invoked, as described in Parameter Validation. 如果允许继续执行,则这些函数返回 -1 并将 errno 设置为 EINVALIf 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 _searchenv _searchenv _wsearchenv


例程所返回的值Routine 必需的标头Required header
_searchenv <stdlib.h><stdlib.h>
_wsearchenv <stdlib.h> 或 <wchar.h><stdlib.h> or <wchar.h>

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


// 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 );  
      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、_wgetenv getenv, _wgetenv
_putenv、_wputenv _putenv, _wputenv
_searchenv_s、_wsearchenv_s_searchenv_s, _wsearchenv_s