_searchenv_s, _wsearchenv_s

Статья
06/09/2015

Ищет файл с помощью путей среды. В этих версиях _searchenv, _wsearchenv усовершенствована безопасность, как описано в разделе Функции безопасности в CRT.

Важно!

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

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.
any	any	NULL	any	EINVAL	Н/Д
NULL	any	any	any	EINVAL	не изменено
any	any	any	<= 0	EINVAL	не изменено

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

Заметки

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

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

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

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

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

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

Подпрограмма 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 );
}