Debugging Tools for Windows

GetSourceEntriesByLine

The GetSourceEntriesByLine and GetSourceEntriesByLineWide methods query symbol information and return locations in the target's memory that correspond to lines in a source file.

IDebugSymbols3::GetSourceEntriesByLine(
    IN ULONG  Line,
    IN PCSTR  File,
    IN ULONG  Flags,
    OUT OPTIONAL PDEBUG_SYMBOL_SOURCE_ENTRY  Entries,
    IN ULONG  EntriesCount,
    OUT OPTIONAL PULONG  EntriesAvail
    );

IDebugSymbols3::GetSourceEntriesByLineWide(
    IN ULONG  Line,
    IN PCWSTR  File,
    IN ULONG  Flags,
    OUT OPTIONAL PDEBUG_SYMBOL_SOURCE_ENTRY  Entries,
    IN ULONG  EntriesCount,
    OUT OPTIONAL PULONG  EntriesAvail
    );

#ifdef UNICODE
#define GetSourceEntriesByLineT GetSourceEntriesByLineWide
#else
#define GetSourceEntriesByLineT GetSourceEntriesByLine
#endif

Parameters

Line

Specifies the line in the source file for which to query. The number for the first line is 1.

File

Specifies the source file. The symbols for each module in the target are queried for this file.

Flags

Specifies bit flags that control the behavior of this method. Flags can be any combination of values from the following table.

Value	Description
DEBUG_GSEL_NO_SYMBOL_LOADS	The debugger engine will only search for the file among the modules whose symbols have already been loaded. Symbols for the other modules will not be loaded. If this option is not set, the debugger engine will load the symbols for all modules until it finds the file specified in File.
DEBUG_GSEL_ALLOW_LOWER	Include all the lines in File before Line in the result.
DEBUG_GSEL_ALLOW_HIGHER	Include all the lines in File after Line in the result.
DEBUG_GSEL_NEAREST_ONLY	Only return at most one result. If DEBUG_GSEL_ALLOW_LOWER or DEBUG_GSEL_ALLOW_HIGHER are set, the returned result will be for a line close to Line but can not be Line if there is no symbol information for that line.

To use the default set of flags, set Flags to DEBUG_GSEL_DEFAULT. This has all the flags in the previous table turned off.

Entries

Receives the locations in the target's memory that correspond to the source lines queried for. Each entry in this array is of type DEBUG_SYMBOL_SOURCE_ENTRY and contains the source line number along with a location in the target's memory.

EntriesCount

Specifies the number of entries in the Entries array.

EntriesAvailable

Receives the number of locations that match the query found in the target's memory.

Return Value

S_OK: The method was successful.
S_FALSE: The method was successful. However, the Entries array was not large enough to hold all the results that matched the query and the extra results were discarded.
E_NOINTERFACE: The query yielded no results. This includes the case where the symbol information was not available for the specified file.

These methods can also return error values. See Return Values for more details.

Interface Version

GetSourceEntriesByLine and GetSourceEntriesByLineWide are available in IDebugSymbols3 and later versions.

Comments

These methods can be used by debugger applications to fetch locations in the target's memory for setting breakpoints or matching source code with disassembled instructions. For example, setting the flags DEBUG_GSEL_ALLOW_HIGHER and DEBUG_GSEL_NEAREST_ONLY will return the target's memory location for the first piece of code starting at the specified line.

For more information about source files, see Using Source Files.

Requirements