_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

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

varnamevarname
要搜索的环境。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,或INCLUDE—,它指定目录路径的列表。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. 如果目标文件是在其中一个目录中,新创建的路径复制到pathnameIf the target file is in one of those directories, the newly created path is copied into 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可能溢出路径名缓冲区并导致意外的行为。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.

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

如果文件名路径名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