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

Syntax

BOOL SetSearchPathMode(
  __in  DWORD Flags
);

Parameters

Flags [in]

The search mode to use.

Value	Meaning
BASE_SEARCH_PATH_ENABLE_SAFE_SEARCHMODE	Enable safe process search mode for the process.
BASE_SEARCH_PATH_DISABLE_SAFE_SEARCHMODE	Disable safe process search mode for the process.
BASE_SEARCH_PATH_PERMANENT	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.

Requirements

See Also

File Management Functions

SearchPath

Send comments about this topic to Microsoft

Build date: 8/19/2010