Searches for a specified file in a specified path.

Syntax

DWORD WINAPI SearchPath(
  __in_opt   LPCTSTR lpPath,
  __in       LPCTSTR lpFileName,
  __in_opt   LPCTSTR lpExtension,
  __in       DWORD nBufferLength,
  __out      LPTSTR lpBuffer,
  __out_opt  LPTSTR *lpFilePart
);

Parameters

lpPath [in, optional]

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.

lpFileName [in]

The name of the file for which to search.

lpExtension [in, optional]

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.

nBufferLength [in]

The size of the buffer that receives the valid path and file name, in TCHARs.

lpBuffer [out]

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

lpFilePart [out, optional]

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.

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 key:

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

When the value of this registry key 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 entry 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.

Requirements

See Also

File Management Functions

FindFirstFile

FindNextFile

GetSystemDirectory

GetWindowsDirectory

SetSearchPathMode

Send comments about this topic to Microsoft

Build date: 11/12/2009