GetNearNameByOffset

The GetNearNameByOffset and GetNearNameByOffsetWide methods return the name of a symbol that is located near the specified location.

HRESULT
  IDebugSymbols::GetNearNameByOffset(
    IN ULONG64  Offset,
    IN LONG  Delta,
    OUT OPTIONAL PSTR  NameBuffer,
    IN ULONG  NameBufferSize,
    OUT OPTIONAL PULONG  NameSize,
    OUT OPTIONAL PULONG64  Displacement
    );

HRESULT
  IDebugSymbols3::GetNearNameByOffsetWide(
    IN ULONG64  Offset,
    IN LONG  Delta,
    OUT OPTIONAL PWSTR  NameBuffer,
    IN ULONG  NameBufferSize,
    OUT OPTIONAL PULONG  NameSize,
    OUT OPTIONAL PULONG64  Displacement
    );

#ifdef UNICODE
#define GetNearNameByOffsetT GetNearNameByOffsetWide
#else
#define GetNearNameByOffsetT GetNearNameByOffset
#endif

Parameters

Offset

Specifies the location in the target's virtual address space of the symbol from which the desired symbol is determined.

Delta

Specifies the relationship between the desired symbol and the symbol located at Offset. If positive, the engine will return the symbol that is Delta symbols after the symbol located at Offset. If negative, the engine will return the symbol that is Delta symbols before the symbol located at Offset.

NameBuffer

Receives the symbol's name. The name is qualified by the module to which the symbol belongs (for example, mymodule!main). If NameBuffer is NULL, this information is not returned.

NameBufferSize

Specifies the size in characters of the buffer NameBuffer.

NameSize

Receives the size in characters of the symbol's name. If NameSize is NULL, this information is not returned.

Displacement

Receives the difference between the value of Offset and the location in the target's memory address space of the symbol. If Displacement is NULL, this information is not returned.

Return Value

S_OK

The method was successful.

S_FALSE

The method was successful. However, the buffer was not large enough to hold the symbol's name so it was truncated.

E_NOINTERFACE

No symbol matching the specifications of Offset and Delta was found.

This method may also return other error values. See Return Values for more details.

Interface Version

GetNearNameByOffset is available in all versions of IDebugSymbols. GetNearNameByOffsetWide is available in IDebugSymbols3 and later versions.

Comments

By increasing or decreasing the value of Delta, these methods can be used to iterate over the target's symbols starting at a particular location.

If Delta is zero, these methods behave the same way as GetNameByOffset.

For more information about symbols and symbol names, see Symbols.

Requirements

Headers: Defined in Dbgeng.h. Include Dbgeng.h.

See Also

GetNameByOffset, GetOffsetByName