_searchenv_s, _wsearchenv_s

Статья
04/10/2013

Поиск файлов с помощью пути среды.Эти версии _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.
любое значение	любое значение	NULL	любое значение	EINVAL	нет
NULL	любое значение	любое значение	любое значение	EINVAL	не изменено
любое значение	любое значение	любое значение	<= 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 );
}