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.
Tip
Starting with Windows 10, Version 1607, you can opt-in to remove the MAX_PATH limitation without prepending "\\?\". See the "Maximum Path Length Limitation" section of Naming Files, Paths, and Namespaces for details.
[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.
| Technology | Supported |
|---|---|
| Server Message Block (SMB) 3.0 protocol | Yes |
| SMB 3.0 Transparent Failover (TFO) | Yes |
| SMB 3.0 with Scale-out File Shares (SO) | Yes |
| Cluster Shared Volume File System (CsvFS) | Yes |
| Resilient File System (ReFS) | Yes |
Note
The processenv.h header defines SearchPath as an alias that automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that is not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows XP [desktop apps only] |
| Minimum supported server | Windows Server 2003 [desktop apps only] |
| Target Platform | Windows |
| Header | processenv.h (include Windows.h) |
| Library | Kernel32.lib |
| DLL | Kernel32.dll |