_searchenv, _wsearchenv

Статья
06/09/2015

Использует пути среды окружения для поиска файла. Существуют более безопасные версии этих функций; см. раздел _searchenv_s, _wsearchenv_s.

Важно!

Этот API не может использоваться в приложениях, выполняемых в Среда выполнения Windows.Дополнительные сведения см. в статье Функции CRT, которые не поддерживаются с ключом /ZW.

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

Параметры

filename
Имя искомого файла.
varname
Среда, в которой выполняется поиск.
pathname
Буфер для хранения полного пути.

Заметки

Процедура _searchenv ищет указанный файл в определенном домене. Переменная varname может быть любой переменной среды или переменной, определенной пользователем, например, PATH, LIB и INCLUDE, которая определяет список путей к каталогу. Поскольку _searchenv учитывается регистр, varname должно соответствовать регистру переменной среды.

Процедура в первую очередь ищет файл в текущей рабочей папке. Если файл найти не удается, то она просматривает каталоги, указанные в переменной среды. Если нужный файл находится в одном из этих каталогов, вновь созданный путь копируется в pathname. Если файл filename не найден, pathname содержит пустую завершенную нулевым символом строку.

Буфер pathname должен быть по крайней мере _MAX_PATH символов длиной, чтобы в него можно было поместить всю длину полученного имени пути. В противном случае — _searchenv может переполнить буфер pathname и привести к непредвиденному поведению.

_wsearchenv — это двухбайтовая версия _searchenv; а аргументы для _wsearchenv представляют собой двухбайтовые строки. В остальных случаях поведение _wsearchenv и _searchenv идентично.

Если filename является пустой строкой, эти функции возвращают ENOENT.

Если параметр filename или pathname указывает на NULL, вызывается обработчик недопустимого параметра, как описано в разделе Проверка параметров. Если выполнение может быть продолжено, эти функции возвращают -1 и устанавливают errno в значение EINVAL.

Дополнительные сведения о errno и кодах ошибок см. в разделе Константы errno.

В C++ эти функции имеют шаблонные перегрузки, которые вызывают более новые и безопасные аналоги этих функций. Дополнительные сведения см. в разделе Безопасные перегрузки шаблонов.

Универсальное текстовое сопоставление функций

Подпрограмма Tchar.h	_UNICODE и _MBCS не определены	_MBCS определено	_UNICODE определено
_tsearchenv	_searchenv	_searchenv	_wsearchenv

Требования

Подпрограмма	Обязательный заголовок
_searchenv	<stdlib.h>
_wsearchenv	<stdlib.h> или <wchar.h>

Дополнительные сведения о совместимости см. в разделе Совместимость.

Пример

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