SearchPathA function (processenv.h)

Searches for a specified file in a specified path.

Syntax

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

Parameters

[in, optional] lpPath

The path to be searched for the file.

If this parameter is NULL, the function searches for a matching file using a registry-dependent system search path. For more information, see the Remarks section.

[in] lpFileName

The name of the file for which to search.

By default, the name is limited to MAX_PATH characters. To extend this limit to 32,767 wide characters, prepend "\\?\" to the path. For more information, see Naming Files, Paths, and Namespaces.

[in, optional] lpExtension

The extension to be added to the file name when searching for the file. The first character of the file name extension must be a period (.). The extension is added only if the specified file name does not end with an extension.

If a file name extension is not required or if the file name contains an extension, this parameter can be NULL.

[in] nBufferLength

The size of the buffer that receives the valid path and file name (including the terminating null character), in TCHARs.

[out] lpBuffer

A pointer to the buffer to receive the path and file name of the file found. The string is a null-terminated string.

[out, optional] lpFilePart

A pointer to the variable to receive the address (within lpBuffer) of the last component of the valid path and file name, which is the address of the character immediately following the final backslash (\) in the path.

Return value

If the function succeeds, the value returned is the length, in TCHARs, of the string that is copied to the buffer, not including the terminating null character. If the return value is greater than nBufferLength, the value returned is the size of the buffer that is required to hold the path, including the terminating null character.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

If the lpPath parameter is NULL, SearchPath searches for a matching file based on the current value of the following registry value:

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

When the value of this REG_DWORD registry value is set to 1, SearchPath first searches the folders that are specified in the system path, and then searches the current working folder. When the value of this registry value is set to 0, the computer first searches the current working folder, and then searches the folders that are specified in the system path. The system default value for this registry key is 0.

The search mode used by the SearchPath function can also be set per-process by calling the SetSearchPathMode function.

The SearchPath function is not recommended as a method of locating a .dll file if the intended use of the output is in a call to the LoadLibrary function. This can result in locating the wrong .dll file because the search order of the SearchPath function differs from the search order used by the LoadLibrary function. If you need to locate and load a .dll file, use the LoadLibrary function.

In Windows 8 and Windows Server 2012, this function is supported by the following technologies.

Requirements

See also

File Management Functions

FindFirstFile

FindNextFile

GetSystemDirectory

GetWindowsDirectory

SetSearchPathMode