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

Статья
08/25/2023

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

Синтаксис

DWORD SearchPathW(
  [in, optional]  LPCWSTR lpPath,
  [in]            LPCWSTR lpFileName,
  [in, optional]  LPCWSTR lpExtension,
  [in]            DWORD   nBufferLength,
  [out]           LPWSTR  lpBuffer,
  [out, optional] LPWSTR  *lpFilePart
);

Параметры

[in, optional] lpPath

Путь, по которому выполняется поиск файла.

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

[in] lpFileName

Имя файла для поиска.

[in, optional] lpExtension

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

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

[in] nBufferLength

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

[out] lpBuffer

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

[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 10 версии 1607 для версии Юникод этой функции (SearchPathW) можно согласиться на удаление ограничения MAX_PATH. Дополнительные сведения см. в разделе "Ограничение максимальной длины пути" статьи Именование файлов, путей и пространств имен .

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

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

Примечание

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

Требования

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