_searchenv_s, _wsearchenv_s

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

Внимание

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

Синтаксис

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

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

Замечания

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

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

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

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

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

По умолчанию глобальное состояние этой функции ограничивается приложением. Чтобы изменить это поведение, см . статью "Глобальное состояние" в CRT.

Сопоставления подпрограмм универсального текста

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

Path for CL.EXE:
C:\Program Files\Microsoft Visual Studio 2010\VC\BIN\CL.EXE

См. также

Элемент управления каталогом
_searchenv, _wsearchenv
getenv, _wgetenv
_putenv, _wputenv