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
SYMOPT_ALLOW_ABSOLUTE_SYMBOLS
0x00000800
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.

SYMOPT_ALLOW_ZERO_ADDRESS
0x01000000
Enables the use of symbols that do not have an address. By default, DbgHelp filters out symbols that do not have an address.
SYMOPT_AUTO_PUBLICS
0x00010000
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.

SYMOPT_CASE_INSENSITIVE
0x00000001
All symbol searches are insensitive to case.
SYMOPT_DEBUG
0x80000000
Pass debug output through OutputDebugString or the SymRegisterCallbackProc64 callback function.
SYMOPT_DEFERRED_LOADS
0x00000004
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.
SYMOPT_DISABLE_SYMSRV_AUTODETECT
0x02000000
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.

SYMOPT_EXACT_SYMBOLS
0x00000400
Do not load an unmatched .pdb file. Do not load export symbols if all else fails.
SYMOPT_FAIL_CRITICAL_ERRORS
0x00000200
Do not display system dialog boxes when there is a media failure such as no media in a drive. Instead, the failure happens silently.
SYMOPT_FAVOR_COMPRESSED
0x00800000
If there is both an uncompressed and a compressed file available, favor the compressed file. This option is good for slow connections.
SYMOPT_FLAT_DIRECTORY
0x00400000
Symbols are stored in the root directory of the default downstream store.

DbgHelp 6.1 and earlier:  This value is not supported.

SYMOPT_IGNORE_CVREC
0x00000080
Ignore path information in the CodeView record of the image header when loading a .pdb file.
SYMOPT_IGNORE_IMAGEDIR
0x00200000
Ignore the image directory.

DbgHelp 6.1 and earlier:  This value is not supported.

SYMOPT_IGNORE_NT_SYMPATH
0x00001000
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.

SYMOPT_INCLUDE_32BIT_MODULES
0x00002000
When debugging on 64-bit Windows, include any 32-bit modules.
SYMOPT_LOAD_ANYTHING
0x00000040
Disable checks to ensure a file (.exe, .dbg., or .pdb) is the correct file. Instead, load the first file located.
SYMOPT_LOAD_LINES
0x00000010
Loads line number information.
SYMOPT_NO_CPP
0x00000008
All C++ decorated symbols containing the symbol separator "::" are replaced by "__". This option exists for debuggers that cannot handle parsing real C++ symbol names.
SYMOPT_NO_IMAGE_SEARCH
0x00020000
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.

SYMOPT_NO_PROMPTS
0x00080000
Prevents prompting for validation from the symbol server.
SYMOPT_NO_PUBLICS
0x00008000
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.

SYMOPT_NO_UNQUALIFIED_LOADS
0x00000100
Prevents symbols from being loaded when the caller examines symbols across multiple modules. Examine only the module whose symbols have already been loaded.
SYMOPT_OVERWRITE
0x00100000
Overwrite the downlevel store from the symbol store.

DbgHelp 6.1 and earlier:  This value is not supported.

SYMOPT_PUBLICS_ONLY
0x00004000
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.

SYMOPT_SECURE
0x00040000
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.

SYMOPT_UNDNAME
0x00000002
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

See also

DbgHelp Functions

SymGetOptions