Edit

Share via

SetSearchPathMode function (winbase.h)

  • Article

Sets the per-process mode that the SearchPath function uses when locating files.

Syntax

BOOL SetSearchPathMode(
  [in] DWORD Flags
);

Parameters

[in] Flags

The search mode to use.

Value Meaning
BASE_SEARCH_PATH_ENABLE_SAFE_SEARCHMODE
0x00000001
 Enable safe process search mode for the process.
BASE_SEARCH_PATH_DISABLE_SAFE_SEARCHMODE
0x00010000
 Disable safe process search mode for the process.
BASE_SEARCH_PATH_PERMANENT
0x00008000
 Optional flag to use in combination with BASE_SEARCH_PATH_ENABLE_SAFE_SEARCHMODE to make this mode permanent for this process. This is done by bitwise OR operation:

(BASE_SEARCH_PATH_ENABLE_SAFE_SEARCHMODE | BASE_SEARCH_PATH_PERMANENT)

This flag cannot be combined with the BASE_SEARCH_PATH_DISABLE_SAFE_SEARCHMODE flag.

Return value

If the operation completes successfully, the SetSearchPathMode function returns a nonzero value.

If the operation fails, the SetSearchPathMode function returns zero. To get extended error information, call the GetLastError function.

If the SetSearchPathMode function fails because a parameter value is not valid, the value returned by the GetLastError function will be ERROR_INVALID_PARAMETER.

If the SetSearchPathMode function fails because the combination of current state and parameter value is not valid, the value returned by the GetLastError function will be ERROR_ACCESS_DENIED. For more information, see the Remarks section.

Remarks

If the SetSearchPathMode function has not been successfully called for the current process, the search mode used by the SearchPath function is obtained from the system registry. For more information, see SearchPath.

After the SetSearchPathMode function has been successfully called for the current process, the setting in the system registry is ignored in favor of the mode most recently set successfully.

If the SetSearchPathMode function has been successfully called for the current process with Flags set to (BASE_SEARCH_PATH_ENABLE_SAFE_SEARCHMODE | BASE_SEARCH_PATH_PERMANENT), safe mode is set permanently for the calling process. Any subsequent calls to the SetSearchPathMode function from within that process that attempt to change the search mode will fail with ERROR_ACCESS_DENIED from the GetLastError function.

Note  Because setting safe search mode permanently cannot be disabled for the life of the process for which is was set, it should be used with careful consideration. This is particularly true for DLL development, where the user of the DLL will be affected by this process-wide setting.
 
It is not possible to permanently disable safe search mode.

This function does not modify the system registry.

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

Requirements

Requirement Value
Minimum supported client Windows 7 [desktop apps only]
Minimum supported server Windows Server 2008 R2 [desktop apps only]
Target Platform Windows
Header winbase.h (include Windows.h)
Library Kernel32.lib
DLL Kernel32.dll
Redistributable KB959426 on Windows XP with SP2 and later and Windows Server 2003 with SP1 and later

See also

File Management Functions

SearchPath