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

Статья
06/02/2023

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

Синтаксис

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), в TCHAR.

[out] lpBuffer

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

[out, optional] lpFilePart

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

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

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

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

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

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

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

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

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

Примечание

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

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Целевая платформа	Windows
Header	processenv.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll