dbgmod.cpp revision c58c758d3642ac45d3f12356c406c631fcd8f538
/* $Id$ */
/** @file
* IPRT - Debug Module Interpreter.
*/
/*
* Copyright (C) 2009 Oracle Corporation
*
* This file is part of VirtualBox Open Source Edition (OSE), as
* available from http://www.virtualbox.org. This file is free software;
* General Public License (GPL) as published by the Free Software
* Foundation, in version 2 as it comes in the "COPYING" file of the
* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
*
* The contents of this file may alternatively be used under the terms
* of the Common Development and Distribution License Version 1.0
* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
* VirtualBox OSE distribution, in which case the provisions of the
* CDDL are applicable instead of those of the GPL.
*
* You may elect to license modified versions of this file under the
* terms and conditions of either the GPL or the CDDL or both.
*/
/*******************************************************************************
* Header Files *
*******************************************************************************/
#include <iprt/initterm.h>
#include <iprt/semaphore.h>
#include <iprt/strcache.h>
/*******************************************************************************
* Structures and Typedefs *
*******************************************************************************/
/** Debug info interpreter registration record. */
typedef struct RTDBGMODREGDBG
{
/** Pointer to the next record. */
struct RTDBGMODREGDBG *pNext;
/** Pointer to the virtual function table for the interpreter. */
/** Usage counter. */
typedef RTDBGMODREGDBG *PRTDBGMODREGDBG;
/** Image interpreter registration record. */
typedef struct RTDBGMODREGIMG
{
/** Pointer to the next record. */
struct RTDBGMODREGIMG *pNext;
/** Pointer to the virtual function table for the interpreter. */
/** Usage counter. */
typedef RTDBGMODREGIMG *PRTDBGMODREGIMG;
/*******************************************************************************
* Defined Constants And Macros *
*******************************************************************************/
/** Validates a debug module handle and returns rc if not valid. */
do { \
} while (0)
/** Locks the debug module. */
#define RTDBGMOD_LOCK(pDbgMod) \
do { \
} while (0)
/** Unlocks the debug module. */
#define RTDBGMOD_UNLOCK(pDbgMod) \
do { \
} while (0)
/*******************************************************************************
* Global Variables *
*******************************************************************************/
/** Init once object for lazy registration of the built-in image and debug
* info interpreters. */
/** List of registered image interpreters. */
static PRTDBGMODREGIMG g_pImgHead;
/** List of registered debug infor interpreters. */
static PRTDBGMODREGDBG g_pDbgHead;
/** String cache for the debug info interpreters.
* RTSTRCACHE is thread safe. */
/**
* Cleanup debug info interpreter globals.
*
* @param enmReason The cause of the termination.
* @param iStatus The meaning of this depends on enmReason.
* @param pvUser User argument, unused.
*/
static DECLCALLBACK(void) rtDbgModTermCallback(RTTERMREASON enmReason, int32_t iStatus, void *pvUser)
{
if (enmReason == RTTERMREASON_UNLOAD)
{
g_pDbgHead = NULL;
while (pDbg)
{
}
g_pImgHead = NULL;
while (pImg)
{
}
}
}
/**
* Internal worker for register a debug interpreter.
*
* Called while owning the write lock or when locking isn't required.
*
* @returns IPRT status code.
* @retval VERR_NO_MEMORY
* @retval VERR_ALREADY_EXISTS
*
* @param pVt The virtual function table of the debug
* module interpreter.
*/
{
/*
* Search or duplicate registration.
*/
{
return VERR_ALREADY_EXISTS;
return VERR_ALREADY_EXISTS;
}
/*
* Create a new record and add it to the end of the list.
*/
if (!pReg)
return VERR_NO_MEMORY;
if (pPrev)
else
g_pDbgHead = pReg;
return VINF_SUCCESS;
}
/**
* Internal worker for register a image interpreter.
*
* Called while owning the write lock or when locking isn't required.
*
* @returns IPRT status code.
* @retval VERR_NO_MEMORY
* @retval VERR_ALREADY_EXISTS
*
* @param pVt The virtual function table of the image
* interpreter.
*/
{
/*
* Search or duplicate registration.
*/
{
return VERR_ALREADY_EXISTS;
return VERR_ALREADY_EXISTS;
}
/*
* Create a new record and add it to the end of the list.
*/
if (!pReg)
return VERR_NO_MEMORY;
if (pPrev)
else
g_pImgHead = pReg;
return VINF_SUCCESS;
}
/**
* the built-in interpreters.
*
* @returns IPRT status code.
* @param pvUser1 NULL.
* @param pvUser2 NULL.
*/
{
/*
* Create the semaphore and string cache.
*/
if (RT_SUCCESS(rc))
{
/*
* Register the interpreters.
*/
if (RT_SUCCESS(rc))
if (RT_SUCCESS(rc))
if (RT_SUCCESS(rc))
{
/*
* Finally, register the IPRT cleanup callback.
*/
if (RT_SUCCESS(rc))
return VINF_SUCCESS;
/* bail out: use the termination callback. */
}
}
else
return rc;
}
DECLINLINE(int) rtDbgModLazyInit(void)
{
}
/**
* Creates a module based on the default debug info container.
*
* This can be used to manually load a module and its symbol. The primary user
* group is the debug info interpreters, which use this API to create an
* efficient debug info container behind the scenes and forward all queries to
* it once the info has been loaded.
*
* @returns IPRT status code.
*
* @param phDbgMod Where to return the module handle.
* @param pszName The name of the module (mandatory).
* @param cbSeg The size of initial segment. If zero, segments will
* have to be added manually using RTDbgModSegmentAdd.
* @param fFlags Flags reserved for future extensions, MBZ for now.
*/
RTDECL(int) RTDbgModCreate(PRTDBGMOD phDbgMod, const char *pszName, RTUINTPTR cbSeg, uint32_t fFlags)
{
/*
* Input validation and lazy initialization.
*/
*phDbgMod = NIL_RTDBGMOD;
int rc = rtDbgModLazyInit();
if (RT_FAILURE(rc))
return rc;
/*
* Allocate a new module instance.
*/
if (!pDbgMod)
return VERR_NO_MEMORY;
if (RT_SUCCESS(rc))
{
{
if (RT_SUCCESS(rc))
{
return rc;
}
}
}
return rc;
}
RTDECL(int) RTDbgModCreateDeferred(PRTDBGMOD phDbgMod, const char *pszFilename, const char *pszName, RTUINTPTR cb, uint32_t fFlags)
{
return VERR_NOT_IMPLEMENTED;
}
RTDECL(int) RTDbgModCreateFromImage(PRTDBGMOD phDbgMod, const char *pszFilename, const char *pszName, uint32_t fFlags)
{
/*
* Input validation and lazy initialization.
*/
*phDbgMod = NIL_RTDBGMOD;
int rc = rtDbgModLazyInit();
if (RT_FAILURE(rc))
return rc;
if (!pszName)
/*
* Allocate a new module instance.
*/
if (!pDbgMod)
return VERR_NO_MEMORY;
if (RT_SUCCESS(rc))
{
{
if (pDbgMod->pszImgFile)
{
/*
* Find an image reader which groks the file.
*/
if (RT_SUCCESS(rc))
{
{
if (RT_SUCCESS(rc))
{
/*
* Find a debug info interpreter.
*/
{
if (RT_SUCCESS(rc))
{
/*
* That's it!
*/
return rc;
}
}
/*
* Image detected, but found no debug info we were
* able to understand.
*/
/** @todo Fall back on exported symbols! */
break;
}
}
/*
* Could it be a file containing raw debug info?
*/
if (!pImg)
{
{
if (RT_SUCCESS(rc))
{
/*
* That's it!
*/
return rc;
}
}
}
/* bail out */
}
}
}
}
return rc;
}
RTDECL(int) RTDbgModCreateFromMap(PRTDBGMOD phDbgMod, const char *pszFilename, const char *pszName, RTUINTPTR uSubtrahend, uint32_t fFlags)
{
/*
* Input validation and lazy initialization.
*/
*phDbgMod = NIL_RTDBGMOD;
int rc = rtDbgModLazyInit();
if (RT_FAILURE(rc))
return rc;
if (!pszName)
/*
* Allocate a new module instance.
*/
if (!pDbgMod)
return VERR_NO_MEMORY;
if (RT_SUCCESS(rc))
{
{
if (pDbgMod->pszDbgFile)
{
/*
* Try the map file readers.
*/
if (RT_SUCCESS(rc))
{
{
{
if (RT_SUCCESS(rc))
{
return rc;
}
}
}
/* bail out */
}
}
}
}
return rc;
}
/**
* Destroys an module after the reference count has reached zero.
*
* @param pDbgMod The module instance.
*/
{
/*
* Close the debug info interpreter first, then the image interpret.
*/
{
}
{
}
/*
* Free the resources.
*/
}
/**
* Retains another reference to the module.
*
* @returns New reference count, UINT32_MAX on invalid handle (asserted).
*
* @param hDbgMod The module handle.
*
* @remarks Will not take any locks.
*/
{
}
/**
* Release a reference to the module.
*
* When the reference count reaches zero, the module is destroyed.
*
* @returns New reference count, UINT32_MAX on invalid handle (asserted).
*
* @param hDbgMod The module handle. The NIL handle is quietly ignored
* and 0 is returned.
*
* @remarks Will not take any locks.
*/
{
if (hDbgMod == NIL_RTDBGMOD)
return 0;
if (!cRefs)
return cRefs;
}
/**
* Gets the module name.
*
* @returns Pointer to a read only string containing the name.
*
* @param hDbgMod The module handle.
*/
{
}
/**
* Converts an image relative address to a segment:offset address.
*
* @returns Segment index on success.
* NIL_RTDBGSEGIDX is returned if the module handle or the RVA are
* invalid.
*
* @param hDbgMod The module handle.
* @param uRva The image relative address to convert.
* @param poffSeg Where to return the segment offset. Optional.
*/
{
return iSeg;
}
/**
* Image size when mapped if segments are mapped adjacently.
*
* For ELF, PE, and Mach-O images this is (usually) a natural query, for LX and
* NE and such it's a bit odder and the answer may not make much sense for them.
*
* @returns Image mapped size.
* RTUINTPTR_MAX is returned if the handle is invalid.
*
* @param hDbgMod The module handle.
*/
{
return cbImage;
}
/**
* Gets the module tag value if any.
*
* @returns The tag. 0 if hDbgMod is invalid.
*
* @param hDbgMod The module handle.
*/
{
}
/**
* Tags or untags the module.
*
* @returns IPRT status code.
* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
*
* @param hDbgMod The module handle.
* @param uTag The tag value. The convention is that 0 is no tag
* and any other value means it's tagged. It's adviced
* to use some kind of unique number like an address
* (global or string cache for instance) to avoid
* collisions with other users
*/
{
return VINF_SUCCESS;
}
/**
* Adds a segment to the module. Optional feature.
*
* This method is intended used for manually constructing debug info for a
* module. The main usage is from other debug info interpreters that want to
* avoid writing a debug info database and instead uses the standard container
* behind the scenes.
*
* @returns IPRT status code.
* @retval VERR_NOT_SUPPORTED if this feature isn't support by the debug info
* interpreter. This is a common return code.
* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
* @retval VERR_DBG_ADDRESS_WRAP if uRva+cb wraps around.
* @retval VERR_DBG_SEGMENT_NAME_OUT_OF_RANGE if pszName is too short or long.
* @retval VERR_INVALID_PARAMETER if fFlags contains undefined flags.
* @retval VERR_DBG_SPECIAL_SEGMENT if *piSeg is a special segment.
* @retval VERR_DBG_INVALID_SEGMENT_INDEX if *piSeg doesn't meet expectations.
*
* @param hDbgMod The module handle.
* @param uRva The image relative address of the segment.
* @param cb The size of the segment.
* @param pszName The segment name. Does not normally need to be
* unique, although this is somewhat up to the
* debug interpreter to decide.
* @param fFlags Segment flags. Reserved for future used, MBZ.
* @param piSeg The segment index or NIL_RTDBGSEGIDX on input.
* The assigned segment index on successful return.
* Optional.
*/
{
/*
* Validate input.
*/
AssertMsgReturn(!piSeg || *piSeg == NIL_RTDBGSEGIDX || *piSeg <= RTDBGSEGIDX_LAST, ("%#x\n", *piSeg), VERR_DBG_SPECIAL_SEGMENT);
/*
* Do the deed.
*/
return rc;
}
/**
* Gets the number of segments in the module.
*
* This is can be used to determine the range which can be passed to
* RTDbgModSegmentByIndex and derivatives.
*
* @returns The segment relative address.
* NIL_RTDBGSEGIDX if the handle is invalid.
*
* @param hDbgMod The module handle.
*/
{
return cSegs;
}
/**
* Query information about a segment.
*
* This can be used together with RTDbgModSegmentCount to enumerate segments.
* The index starts a 0 and stops one below RTDbgModSegmentCount.
*
* @returns IPRT status code.
* @retval VERR_DBG_INVALID_SEGMENT_INDEX if iSeg is too high.
* @retval VERR_DBG_SPECIAL_SEGMENT if iSeg indicates a special segment.
* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
*
* @param hDbgMod The module handle.
* @param iSeg The segment index. No special segments.
* @param pSegInfo Where to return the segment info. The
* RTDBGSEGMENT::Address member will be set to
* RTUINTPTR_MAX or the load address used at link time.
*/
{
return rc;
}
/**
* Gets the size of a segment.
*
* This is a just a wrapper around RTDbgModSegmentByIndex.
*
* @returns The segment size.
* RTUINTPTR_MAX is returned if either the handle and segment index are
* invalid.
*
* @param hDbgMod The module handle.
* @param iSeg The segment index. RTDBGSEGIDX_ABS is not allowed.
* If RTDBGSEGIDX_RVA is used, the functions returns
* the same value as RTDbgModImageSize.
*/
{
if (iSeg == RTDBGSEGIDX_RVA)
return RTDbgModImageSize(hDbgMod);
}
/**
* Gets the image relative address of a segment.
*
* This is a just a wrapper around RTDbgModSegmentByIndex.
*
* @returns The segment relative address.
* RTUINTPTR_MAX is returned if either the handle and segment index are
* invalid.
*
* @param hDbgMod The module handle.
* @param iSeg The segment index. No special segment indexes
* allowed (asserted).
*/
{
}
/**
* Adds a line number to the module.
*
* @returns IPRT status code.
* @retval VERR_NOT_SUPPORTED if the module interpret doesn't support adding
* custom symbols. This is a common place occurrence.
* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
* @retval VERR_DBG_SYMBOL_NAME_OUT_OF_RANGE if the symbol name is too long or
* short.
* @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
* it's not inside any of the segments defined by the module.
* @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
* @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
* end of the segment.
* @retval VERR_DBG_ADDRESS_WRAP if off+cb wraps around.
* @retval VERR_INVALID_PARAMETER if the symbol flags sets undefined bits.
*
* @param hDbgMod The module handle.
* @param pszSymbol The symbol name.
* @param iSeg The segment index.
* @param off The segment offset.
* @param cb The size of the symbol. Can be zero, although this
* may depend somewhat on the debug interpreter.
* @param fFlags Symbol flags. Reserved for the future, MBZ.
* @param piOrdinal Where to return the symbol ordinal on success. If
* the interpreter doesn't do ordinals, this will be set to
* UINT32_MAX. Optional.
*/
RTDECL(int) RTDbgModSymbolAdd(RTDBGMOD hDbgMod, const char *pszSymbol, RTDBGSEGIDX iSeg, RTUINTPTR off,
{
/*
* Validate input.
*/
|| ( iSeg >= RTDBGSEGIDX_SPECIAL_FIRST
&& iSeg <= RTDBGSEGIDX_SPECIAL_LAST),
("%#x\n", iSeg),
/*
* Convert RVAs.
*/
if (iSeg == RTDBGSEGIDX_RVA)
{
if (iSeg == NIL_RTDBGSEGIDX)
{
return VERR_DBG_INVALID_RVA;
}
}
/*
* Get down to business.
*/
int rc = pDbgMod->pDbgVt->pfnSymbolAdd(pDbgMod, pszSymbol, cchSymbol, iSeg, off, cb, fFlags, piOrdinal);
return rc;
}
/**
* Gets the symbol count.
*
* This can be used together wtih RTDbgModSymbolByOrdinal or
* RTDbgModSymbolByOrdinalA to enumerate all the symbols.
*
* @returns The number of symbols in the module.
* UINT32_MAX is returned if the module handle is invalid or some other
* error occurs.
*
* @param hDbgMod The module handle.
*/
{
return cSymbols;
}
/**
* Queries symbol information by ordinal number.
*
* @returns IPRT status code.
* @retval VERR_SYMBOL_NOT_FOUND if there is no symbol at the given number.
* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
* @retval VERR_NOT_SUPPORTED if lookup by ordinal is not supported.
*
* @param hDbgMod The module handle.
* @param iOrdinal The symbol ordinal number. 0-based. The highest
* number is RTDbgModSymbolCount() - 1.
* @param pSymInfo Where to store the symbol information.
*/
{
return rc;
}
/**
* Queries symbol information by ordinal number.
*
* @returns IPRT status code.
* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
* @retval VERR_NOT_SUPPORTED if lookup by ordinal is not supported.
* @retval VERR_SYMBOL_NOT_FOUND if there is no symbol at the given number.
* @retval VERR_NO_MEMORY if RTDbgSymbolAlloc fails.
*
* @param hDbgMod The module handle.
* @param iOrdinal The symbol ordinal number. 0-based. The highest
* number is RTDbgModSymbolCount() - 1.
* @param ppSymInfo Where to store the pointer to the returned
* symbol information. Always set. Free with
* RTDbgSymbolFree.
*/
{
if (!pSymInfo)
return VERR_NO_MEMORY;
if (RT_SUCCESS(rc))
else
return rc;
}
/**
* Queries symbol information by address.
*
* The returned symbol is what the debug info interpreter considers the symbol
* most applicable to the specified address. This usually means a symbol with an
* address equal or lower than the requested.
*
* @returns IPRT status code.
* @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
* @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
* it's not inside any of the segments defined by the module.
* @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
* @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
* end of the segment.
*
* @param hDbgMod The module handle.
* @param iSeg The segment number.
* @param off The offset into the segment.
* @param poffDisp Where to store the distance between the
* specified address and the returned symbol.
* Optional.
* @param pSymInfo Where to store the symbol information.
*/
RTDECL(int) RTDbgModSymbolByAddr(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, PRTINTPTR poffDisp, PRTDBGSYMBOL pSymInfo)
{
/*
* Validate input.
*/
/*
* Convert RVAs.
*/
if (iSeg == RTDBGSEGIDX_RVA)
{
if (iSeg == NIL_RTDBGSEGIDX)
{
return VERR_DBG_INVALID_RVA;
}
}
/*
* Get down to business.
*/
return rc;
}
/**
* Queries symbol information by address.
*
* The returned symbol is what the debug info interpreter considers the symbol
* most applicable to the specified address. This usually means a symbol with an
* address equal or lower than the requested.
*
* @returns IPRT status code.
* @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
* @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
* it's not inside any of the segments defined by the module.
* @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
* @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
* end of the segment.
* @retval VERR_NO_MEMORY if RTDbgSymbolAlloc fails.
*
* @param hDbgMod The module handle.
* @param iSeg The segment index.
* @param off The offset into the segment.
* @param poffDisp Where to store the distance between the
* specified address and the returned symbol. Optional.
* @param ppSymInfo Where to store the pointer to the returned
* symbol information. Always set. Free with
* RTDbgSymbolFree.
*/
RTDECL(int) RTDbgModSymbolByAddrA(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, PRTINTPTR poffDisp, PRTDBGSYMBOL *ppSymInfo)
{
if (!pSymInfo)
return VERR_NO_MEMORY;
if (RT_SUCCESS(rc))
else
return rc;
}
/**
* Queries symbol information by symbol name.
*
* @returns IPRT status code.
* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
* @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
* @retval VERR_DBG_SYMBOL_NAME_OUT_OF_RANGE if the symbol name is too long or
* short.
*
* @param hDbgMod The module handle.
* @param pszSymbol The symbol name.
* @param pSymInfo Where to store the symbol information.
*/
{
/*
* Validate input.
*/
/*
* Make the query.
*/
return rc;
}
/**
* Queries symbol information by symbol name.
*
* @returns IPRT status code.
* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
* @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
* @retval VERR_DBG_SYMBOL_NAME_OUT_OF_RANGE if the symbol name is too long or
* short.
* @retval VERR_NO_MEMORY if RTDbgSymbolAlloc fails.
*
* @param hDbgMod The module handle.
* @param pszSymbol The symbol name.
* @param ppSymInfo Where to store the pointer to the returned
* symbol information. Always set. Free with
* RTDbgSymbolFree.
*/
{
if (!pSymInfo)
return VERR_NO_MEMORY;
if (RT_SUCCESS(rc))
else
return rc;
}
/**
* Adds a line number to the module.
*
* @returns IPRT status code.
* @retval VERR_NOT_SUPPORTED if the module interpret doesn't support adding
* custom symbols. This should be consider a normal response.
* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
* @retval VERR_DBG_FILE_NAME_OUT_OF_RANGE if the file name is too longer or
* empty.
* @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
* it's not inside any of the segments defined by the module.
* @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
* @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
* end of the segment.
* @retval VERR_INVALID_PARAMETER if the line number flags sets undefined bits.
*
* @param hDbgMod The module handle.
* @param pszFile The file name.
* @param uLineNo The line number.
* @param iSeg The segment index.
* @param off The segment offset.
* @param piOrdinal Where to return the line number ordinal on
* success. If the interpreter doesn't do ordinals,
* this will be set to UINT32_MAX. Optional.
*/
{
/*
* Validate input.
*/
|| iSeg == RTDBGSEGIDX_RVA,
("%#x\n", iSeg),
/*
* Convert RVAs.
*/
if (iSeg == RTDBGSEGIDX_RVA)
{
if (iSeg == NIL_RTDBGSEGIDX)
{
return VERR_DBG_INVALID_RVA;
}
}
/*
* Get down to business.
*/
return rc;
}
/**
* Gets the line number count.
*
* This can be used together wtih RTDbgModLineByOrdinal or RTDbgModSymbolByLineA
* to enumerate all the line number information.
*
* @returns The number of line numbers in the module.
* UINT32_MAX is returned if the module handle is invalid or some other
* error occurs.
*
* @param hDbgMod The module handle.
*/
{
return cLineNumbers;
}
/**
* Queries line number information by ordinal number.
*
* This can be used to enumerate the line numbers for the module. Use
* RTDbgModLineCount() to figure the end of the ordinals.
*
* @returns IPRT status code.
* @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
* @retval VERR_DBG_LINE_NOT_FOUND if there is no line number with that
* ordinal.
* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
* @param hDbgMod The module handle.
* @param iOrdinal The line number ordinal number.
* @param pLineInfo Where to store the information about the line
* number.
*/
{
return rc;
}
/**
* Queries line number information by ordinal number.
*
* This can be used to enumerate the line numbers for the module. Use
* RTDbgModLineCount() to figure the end of the ordinals.
*
* @returns IPRT status code.
* @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
* @retval VERR_DBG_LINE_NOT_FOUND if there is no line number with that
* ordinal.
* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
* @retval VERR_NO_MEMORY if RTDbgLineAlloc fails.
*
* @param hDbgMod The module handle.
* @param iOrdinal The line number ordinal number.
* @param ppLineInfo Where to store the pointer to the returned line
* number information. Always set. Free with
* RTDbgLineFree.
*/
{
*ppLineInfo = NULL;
if (!pLineInfo)
return VERR_NO_MEMORY;
if (RT_SUCCESS(rc))
*ppLineInfo = pLineInfo;
else
return rc;
}
/**
* Queries line number information by address.
*
* The returned line number is what the debug info interpreter considers the
* one most applicable to the specified address. This usually means a line
* number with an address equal or lower than the requested.
*
* @returns IPRT status code.
* @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
* @retval VERR_DBG_LINE_NOT_FOUND if no suitable line number was found.
* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
* @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
* it's not inside any of the segments defined by the module.
* @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
* @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
* end of the segment.
*
* @param hDbgMod The module handle.
* @param iSeg The segment number.
* @param off The offset into the segment.
* @param poffDisp Where to store the distance between the
* specified address and the returned symbol.
* Optional.
* @param pLineInfo Where to store the line number information.
*/
RTDECL(int) RTDbgModLineByAddr(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, PRTINTPTR poffDisp, PRTDBGLINE pLineInfo)
{
/*
* Validate input.
*/
/*
* Convert RVAs.
*/
if (iSeg == RTDBGSEGIDX_RVA)
{
if (iSeg == NIL_RTDBGSEGIDX)
{
return VERR_DBG_INVALID_RVA;
}
}
return rc;
}
/**
* Queries line number information by address.
*
* The returned line number is what the debug info interpreter considers the
* one most applicable to the specified address. This usually means a line
* number with an address equal or lower than the requested.
*
* @returns IPRT status code.
* @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
* @retval VERR_DBG_LINE_NOT_FOUND if no suitable line number was found.
* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
* @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
* it's not inside any of the segments defined by the module.
* @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
* @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
* end of the segment.
* @retval VERR_NO_MEMORY if RTDbgLineAlloc fails.
*
* @param hDbgMod The module handle.
* @param iSeg The segment number.
* @param off The offset into the segment.
* @param poffDisp Where to store the distance between the
* specified address and the returned symbol.
* Optional.
* @param ppLineInfo Where to store the pointer to the returned line
* number information. Always set. Free with
* RTDbgLineFree.
*/
RTDECL(int) RTDbgModLineByAddrA(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, PRTINTPTR poffDisp, PRTDBGLINE *ppLineInfo)
{
*ppLineInfo = NULL;
if (!pLineInfo)
return VERR_NO_MEMORY;
if (RT_SUCCESS(rc))
*ppLineInfo = pLineInfo;
else
return rc;
}