SymSetOptions Function

Sets the options mask.

DWORD WINAPI SymSetOptions(
  __in          DWORD SymOptions
);

Parameters

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	TBD
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 Windows 2000 and earlier 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.

Example Code

For an example, see Initializing the Symbol Handler.

Requirements

See Also

DbgHelp Functions
SymGetOptions

Send comments about this topic to Microsoft

Build date: 9/25/2007