Функция SearchPathA (processenv.h)

Статья
11/20/2024

Выполняет поиск указанного файла в указанном пути.

Синтаксис

DWORD SearchPathA(
  [in, optional]  LPCSTR lpPath,
  [in]            LPCSTR lpFileName,
  [in, optional]  LPCSTR lpExtension,
  [in]            DWORD  nBufferLength,
  [out]           LPSTR  lpBuffer,
  [out, optional] LPSTR  *lpFilePart
);

Параметры

[in, optional] lpPath

Путь для поиска файла.

Если этот параметр null, функция ищет соответствующий файл с помощью пути поиска в системе, зависящем от реестра. Дополнительные сведения см. в разделе "Примечания".

[in] lpFileName

Имя файла, для которого выполняется поиск.

По умолчанию имя ограничено MAX_PATH символами. Чтобы расширить это ограничение до 32 767 расширенных символов, добавьте "\\?\" в путь. Дополнительные сведения см. в именовании файлов, путей и пространств имен.

Кончик

Начиная с Windows 10 версии 1607, вы можете отказаться от ограничения MAX_PATH без предустановки "\\?\". Дополнительные сведения см. в разделе "Ограничение максимальной длины пути" файлы именования, пути и пространства имен.

[in, optional] lpExtension

Расширение, добавляемое в имя файла при поиске файла. Первый символ расширения имени файла должен быть периодом (.). Расширение добавляется только в том случае, если указанное имя файла не заканчивается расширением.

Если расширение имени файла не является обязательным или если имя файла содержит расширение, этот параметр может быть NULL.

[in] nBufferLength

Размер буфера, получающего допустимый путь и имя файла (включая конечный символ NULL), в TCHARs.

[out] lpBuffer

Указатель на буфер для получения пути и имени файла найденного файла. Строка является строкой, завершающейся значением NULL.

[out, optional] lpFilePart

Указатель на переменную для получения адреса (в lpBuffer) последнего компонента допустимого пути и имени файла, который является адресом символа сразу после окончательной обратной косой черты (\) в пути.

Возвращаемое значение

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

Если функция завершается ошибкой, возвращаемое значение равно нулю. Чтобы получить расширенные сведения об ошибке, вызовите GetLastError.

Замечания

Если параметр lpPath имеет значение NULL, SearchPath выполняет поиск соответствующего файла на основе текущего значения реестра:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\SafeProcessSearchMode

Если для этого значения реестра REG_DWORD задано значение 1, SearchPath сначала выполняет поиск папок, указанных в системном пути, а затем выполняет поиск текущей рабочей папки. Если для этого значения реестра задано значение 0, компьютер сначала выполняет поиск текущей рабочей папки, а затем выполняет поиск папок, указанных в системном пути. Системное значение по умолчанию для этого раздела реестра равно 0.

Режим поиска, используемый функцией SearchPath , также можно задать для каждого процесса путем вызова функции SetSearchPathMode.

Функция SearchPath не рекомендуется в качестве метода поиска файла .dll, если предполагаемое использование выходных данных вызывает функцию LoadLibrary. Это может привести к поиску неправильного .dll файла, так как порядок поиска функции SearchPath отличается от порядка поиска, используемого функцией LoadLibrary. Если необходимо найти и загрузить файл .dll, используйте функцию LoadLibrary.

В Windows 8 и Windows Server 2012 эта функция поддерживается следующими технологиями.

Технологии	Поддержанный
Протокол SMB 3.0	Да
Отработка отказа SMB 3.0 (TFO)	Да
SMB 3.0 с масштабируемыми общими папками (SO)	Да
Файловая система общего тома кластера (CSVFS)	Да
Отказоустойчивая файловая система (ReFS)	Да

Заметка

Заголовок processenv.h определяет SearchPath как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP [только классические приложения]
минимальный поддерживаемый сервер	Windows Server 2003 [только классические приложения]
целевая платформа	Виндоус
заголовка	processenv.h (включая Windows.h)
библиотеки	Kernel32.lib
DLL	Kernel32.dll