SymSetOptions function (dbghelp.h)
Sets the options mask.
Syntax
DWORD IMAGEAPI SymSetOptions(
[in] DWORD SymOptions
);
Parameters
[in] SymOptions
The symbol options. Zero is a valid value and indicates that all options are turned off. The options values are combined using the OR operator to form a valid options value. The following are valid values.
| Value | Meaning |
|---|---|
|
Enables the use of symbols that are stored with absolute addresses. Most symbols are stored as RVAs from the base of the module. DbgHelp translates them to absolute addresses. There are symbols that are stored as an absolute address. These have very specialized purposes and are typically not used.
DbgHelp 5.1 and earlier: This value is not supported. |
|
Enables the use of symbols that do not have an address. By default, DbgHelp filters out symbols that do not have an address. |
|
Do not search the public symbols when searching for symbols by address, or when enumerating symbols, unless they were not found in the global symbols or within the current scope. This option has no effect with SYMOPT_PUBLICS_ONLY.
DbgHelp 5.1 and earlier: This value is not supported. |
|
All symbol searches are insensitive to case. |
|
Pass debug output through OutputDebugString or the SymRegisterCallbackProc64 callback function. |
|
Symbols are not loaded until a reference is made requiring the symbols be loaded. This is the fastest, most efficient way to use the symbol handler. |
|
Disables the auto-detection of symbol server stores in the symbol path, even without the "SRV*" designation, maintaining compatibility with previous behavior.
DbgHelp 6.6 and earlier: This value is not supported. |
|
Do not load an unmatched .pdb file. Do not load export symbols if all else fails. |
|
Do not display system dialog boxes when there is a media failure such as no media in a drive. Instead, the failure happens silently. |
|
If there is both an uncompressed and a compressed file available, favor the compressed file. This option is good for slow connections. |
|
Symbols are stored in the root directory of the default downstream store.
DbgHelp 6.1 and earlier: This value is not supported. |
|
Ignore path information in the CodeView record of the image header when loading a .pdb file. |
|
Ignore the image directory.
DbgHelp 6.1 and earlier: This value is not supported. |
|
Do not use the path specified by _NT_SYMBOL_PATH if the user calls
SymSetSearchPath without a valid path.
DbgHelp 5.1: This value is not supported. |
|
When debugging on 64-bit Windows, include any 32-bit modules. |
|
Disable checks to ensure a file (.exe, .dbg., or .pdb) is the correct file. Instead, load the first file located. |
|
Loads line number information. |
|
All C++ decorated symbols containing the symbol separator "::" are replaced by "__". This option exists for debuggers that cannot handle parsing real C++ symbol names. |
|
Do not search the image for the symbol path when loading the symbols for a module if the module header cannot be read.
DbgHelp 5.1: This value is not supported. |
|
Prevents prompting for validation from the symbol server. |
|
Do not search the publics table for symbols. This option should have little effect because there are copies of the public symbols in the globals table.
DbgHelp 5.1: This value is not supported. |
|
Prevents symbols from being loaded when the caller examines symbols across multiple modules. Examine only the module whose symbols have already been loaded. |
|
Overwrite the downlevel store from the symbol store.
DbgHelp 6.1 and earlier: This value is not supported. |
|
Do not use private symbols. The version of DbgHelp that shipped with earlier Windows release supported only public symbols; this option provides compatibility with this limitation.
DbgHelp 5.1: This value is not supported. |
|
DbgHelp will not load any symbol server other than SymSrv. SymSrv will not use the downstream store specified in _NT_SYMBOL_PATH. After this flag has been set, it cannot be cleared.
DbgHelp 6.0 and 6.1: This flag can be cleared. DbgHelp 5.1: This value is not supported. |
|
All symbols are presented in undecorated form.
This option has no effect on global or local symbols because they are stored undecorated. This option applies only to public symbols. |
Return value
The function returns the current options mask.
Remarks
The options value can be changed any number of times while the library is in use by an application. The option change affects all future calls to the symbol handler.
To get the current options mask, call the SymGetOptions function.
All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.
Examples
For an example, see Initializing the Symbol Handler.
Requirements
| Requirement | Value |
|---|---|
| Target Platform | Windows |
| Header | dbghelp.h |
| Library | Dbghelp.lib |
| DLL | Dbghelp.dll |
| Redistributable | DbgHelp.dll 5.1 or later |