dbg.h revision b7a07b07543924f45c1fffd2f90de582038b8ba6
/** Symbol Flags. (reserved). */ * This is set to UINT32_MAX if the ordinals aren't supported. */ /** Pointer to debug symbol. */ /** Pointer to const debug symbol. */ * Allocate a new symbol structure. * @returns Pointer to a new structure on success, NULL on failure. * Duplicates a symbol structure. * @returns Pointer to duplicate on success, NULL on failure. * @param pSymInfo The symbol info to duplicate. * Free a symbol structure previously allocated by a RTDbg method. * @param pSymInfo The symbol info to free. NULL is ignored. /** Max length (including '\\0') of a debug info file name. */ * Debug line number information. * This depends a bit who you ask. It will be the same as offSeg when you * as RTDbgMod, but the mapping address if you ask RTDbgAs. */ /** Offset into the segment specified by iSeg. */ * This is set to UINT32_MAX if the ordinals aren't supported. */ /** Pointer to debug line number. */ /** Pointer to const debug line number. */ * Allocate a new line number structure. * @returns Pointer to a new structure on success, NULL on failure. * Duplicates a line number structure. * @returns Pointer to duplicate on success, NULL on failure. * @param pLine The line number to duplicate. * Free a line number structure previously allocated by a RTDbg method. * @param pLine The line number to free. NULL is ignored. /** @defgroup grp_rt_dbgcfg RTDbgCfg - Debugging Configuration * The settings used when loading and processing debug info is kept in a * RTDBGCFG instance since it's generally shared for a whole debugging session * and anyhow would be a major pain to pass as individual parameters to each * call. The debugging config API not only keeps the settings information but * also provide APIs for making use of it, and in some cases, like for instance * symbol severs, retriving and maintaining it. * @todo Work in progress - APIs are still missing, adding when needed. /** Debugging configuration handle. */ /** Pointer to a debugging configuration handle. */ /** NIL debug configuration handle. */ /** @name RTDBGCFG_FLAGS_XXX - Debugging configuration flags. /** Use deferred loading. */ /** Don't use the symbol server (http). */ /** Don't use system search paths. * On windows this means not using _NT_ALT_SYMBOL_PATH, _NT_SYMBOL_PATH, * _NT_SOURCE_PATH, and _NT_EXECUTABLE_PATH. * On other systems the effect has yet to be determined. */ /** Don't search the debug and image paths recursively. */ /** Don't search the source paths recursively. */ * Debugging configuration properties. * The search paths are using the DOS convention of semicolon as separator * character. The the special 'srv' + asterisk syntax known from the windows * debugger search paths are also supported to some extent, as is 'cache' + /** The customary invalid 0 value. */ * The environment variable can be specified as a unsigned value or one or more * mnemonics separated by spaces. */ /** List of paths to search for symbol files and images. /** List of symbol file suffixes (semicolon separated). /** List of paths to search for source files. /** End of valid values. */ /** The customary 32-bit type hack. */ * Configuration property change operation. /** Customary invalid 0 value. */ /** Replace the current value with the given one. */ /** Append the given value to the existing one. For integer values this is * considered a bitwise OR operation. */ /** Prepend the given value to the existing one. For integer values this is * considered a bitwise OR operation. */ /** Removes the value from the existing one. For interger values the value is * complemented and ANDed with the existing one, clearing all the specified /** End of valid values. */ /** Customary 32-bit type hack. */ * Initializes a debugging configuration. * @returns IPRT status code. * @param phDbgCfg Where to return the configuration handle. * @param pszEnvVarPrefix The environment variable prefix. If NULL, the * environment is not consulted. * @sa RTDbgCfgChangeString, RTDbgCfgChangeUInt. * Retains a new reference to a debugging config. * @returns New reference count. * UINT32_MAX is returned if the handle is invalid (asserted). * @param hDbgCfg The config handle. * Releases a references to a debugging config. * @returns New reference count, if 0 the config was freed. UINT32_MAX is * returned if the handle is invalid (asserted). * @param hDbgCfg The config handle. * Changes a property value by string. * For string values the string is used more or less as given. For integer * values and flags, it can contains both values (ORed together) or property * specific mnemonics (ORed / ~ANDed). * @returns IPRT status code. * @retval VERR_DBG_CFG_INVALID_VALUE * @param hDbgCfg The debugging configuration handle. * @param enmProp The property to change. * @param enmOp How to change the property. * @param pszValue The property value to apply. * Changes a property value by unsigned integer (64-bit). * This can only be applied to integer and flag properties. * @returns IPRT status code. * @retval VERR_DBG_CFG_NOT_UINT_PROP * @param hDbgCfg The debugging configuration handle. * @param enmProp The property to change. * @param enmOp How to change the property. * @param uValue The property value to apply. * Query a property value as string. * Integer and flags properties are returned as a list of mnemonics if possible, * otherwise as simple hex values. * @returns IPRT status code. * @retval VERR_BUFFER_OVERFLOW if there isn't sufficient buffer space. Nothing * @param hDbgCfg The debugging configuration handle. * @param enmProp The property to change. * @param pszValue The output buffer. * @param cbValue The size of the output buffer. * Query a property value as unsigned integer (64-bit). * Only integer and flags properties can be queried this way. * @returns IPRT status code. * @retval VERR_DBG_CFG_NOT_UINT_PROP * @param hDbgCfg The debugging configuration handle. * @param enmProp The property to change. * @param puValue Where to return the value. /** @defgroup grp_rt_dbgas RTDbgAs - Debug Address Space * Creates an empty address space. * @returns IPRT status code. * @param phDbgAs Where to store the address space handle on success. * @param FirstAddr The first address in the address space. * @param LastAddr The last address in the address space. * @param pszName The name of the address space. * Variant of RTDbgAsCreate that takes a name format string. * @returns IPRT status code. * @param phDbgAs Where to store the address space handle on success. * @param FirstAddr The first address in the address space. * @param LastAddr The last address in the address space. * @param pszNameFmt The name format of the address space. * @param va Format arguments. * Variant of RTDbgAsCreate that takes a name format string. * @returns IPRT status code. * @param phDbgAs Where to store the address space handle on success. * @param FirstAddr The first address in the address space. * @param LastAddr The last address in the address space. * @param pszNameFmt The name format of the address space. * @param ... Format arguments. * Retains a reference to the address space. * @returns New reference count, UINT32_MAX on invalid handle (asserted). * @param hDbgAs The address space handle. * @remarks Will not take any locks. * Release a reference to the address space. * When the reference count reaches zero, the address space is destroyed. * That means unlinking all the modules it currently contains, potentially * causing some or all of them to be destroyed as they are managed by * @returns New reference count, UINT32_MAX on invalid handle (asserted). * @param hDbgAs The address space handle. The NIL handle is quietly * ignored and 0 is returned. * @remarks Will not take any locks. * Gets the name of an address space. * @returns read only address space name. * NULL if hDbgAs is invalid. * @param hDbgAs The address space handle. * @remarks Will not take any locks. * Gets the first address in an address space. * 0 if hDbgAs is invalid. * @param hDbgAs The address space handle. * @remarks Will not take any locks. * Gets the last address in an address space. * 0 if hDbgAs is invalid. * @param hDbgAs The address space handle. * @remarks Will not take any locks. * Gets the number of modules in the address space. * This can be used together with RTDbgAsModuleByIndex * to enumerate the modules. * @returns The number of modules. * @param hDbgAs The address space handle. * @remarks Will not take any locks. /** @name Flags for RTDbgAsModuleLink and RTDbgAsModuleLinkSeg /** Replace all conflicting module. * (The conflicting modules will be removed the address space and their * references released.) */ /** Mask containing the valid flags. */ * Links a module into the address space at the give address. * The size of the mapping is determined using RTDbgModImageSize(). * @returns IPRT status code. * @retval VERR_OUT_OF_RANGE if the specified address will put the module * outside the address space. * @retval VERR_ADDRESS_CONFLICT if the mapping clashes with existing mappings. * @param hDbgAs The address space handle. * @param hDbgMod The module handle of the module to be linked in. * @param ImageAddr The address to link the module at. * @param fFlags See RTDBGASLINK_FLAGS_*. * Links a segment into the address space at the give address. * The size of the mapping is determined using RTDbgModSegmentSize(). * @returns IPRT status code. * @retval VERR_OUT_OF_RANGE if the specified address will put the module * outside the address space. * @retval VERR_ADDRESS_CONFLICT if the mapping clashes with existing mappings. * @param hDbgAs The address space handle. * @param hDbgMod The module handle. * @param iSeg The segment number (0-based) of the segment to be * @param SegAddr The address to link the segment at. * @param fFlags See RTDBGASLINK_FLAGS_*. * Unlinks all the mappings of a module from the address space. * @returns IPRT status code. * @retval VERR_NOT_FOUND if the module wasn't found. * @param hDbgAs The address space handle. * @param hDbgMod The module handle of the module to be unlinked. * Unlinks the mapping at the specified address. * @returns IPRT status code. * @retval VERR_NOT_FOUND if no module or segment is mapped at that address. * @param hDbgAs The address space handle. * @param Addr The address within the mapping to be unlinked. * Get a the handle of a module in the address space by is index. * @returns A retained handle to the specified module. The caller must release * the returned reference. * NIL_RTDBGMOD if invalid index or handle. * @param hDbgAs The address space handle. * @param iModule The index of the module to get. * @remarks The module indexes may change after calls to RTDbgAsModuleLink, * RTDbgAsModuleLinkSeg, RTDbgAsModuleUnlink and * RTDbgAsModuleUnlinkByAddr. * Queries mapping module information by handle. * @returns IPRT status code. * @retval VERR_NOT_FOUND if no mapping was found at the specified address. * @param hDbgAs The address space handle. * @param Addr Address within the mapping of the module or segment. * @param phMod Where to the return the retained module handle. * @param pAddr Where to return the base address of the mapping. * @param piSeg Where to return the segment index. This is set to * NIL if the entire module is mapped as a single * Queries mapping module information by name. * @returns IPRT status code. * @retval VERR_NOT_FOUND if no mapping was found at the specified address. * @retval VERR_OUT_OF_RANGE if the name index was out of range. * @param hDbgAs The address space handle. * @param pszName The module name. * @param iName There can be more than one module by the same name * in an address space. This argument indicates which * @param phMod Where to the return the retained module handle. * Information about a mapping. * This is used by RTDbgAsModuleGetMapByIndex. /** The mapping address. */ /** The segment mapped there. * This is NIL_RTDBGSEGIDX if the entire module image is mapped here. */ /** Pointer to info about an address space mapping. */ /** Pointer to const info about an address space mapping. */ * Queries mapping information for a module given by index. * @returns IRPT status code. * @retval VERR_INVALID_HANDLE if hDbgAs is invalid. * @retval VERR_OUT_OF_RANGE if the name index was out of range. * @retval VINF_BUFFER_OVERFLOW if the array is too small and the returned * information is incomplete. * @param hDbgAs The address space handle. * @param iModule The index of the module to get. * @param paMappings Where to return the mapping information. The buffer * size is given by *pcMappings. * @param pcMappings IN: Size of the paMappings array. OUT: The number of * @param fFlags Flags for reserved for future use. MBZ. * @remarks See remarks for RTDbgAsModuleByIndex regarding the volatility of the * Adds a symbol to a module in the address space. * @returns IPRT status code. See RTDbgModSymbolAdd for more specific ones. * @retval VERR_INVALID_HANDLE if hDbgAs is invalid. * @retval VERR_NOT_FOUND if no module was found at the specified address. * @retval VERR_NOT_SUPPORTED if the module interpret doesn't support adding * @param hDbgAs The address space handle. * @param pszSymbol The symbol name. * @param Addr The address of the symbol. * @param cb The size of the symbol. * @param fFlags Symbol flags. * @param piOrdinal Where to return the symbol ordinal on success. If * the interpreter doesn't do ordinals, this will be set to * Query a symbol by address. * @returns IPRT status code. See RTDbgModSymbolAddr for more specific ones. * @retval VERR_INVALID_HANDLE if hDbgAs is invalid. * @retval VERR_NOT_FOUND if the address couldn't be mapped to a module. * @retval VERR_INVALID_PARAMETER if incorrect flags. * @param hDbgAs The address space handle. * @param Addr The address which closest symbol is requested. * @param fFlags Symbol search flags, see RTDBGSYMADDR_FLAGS_XXX. * @param poffDisp Where to return the distance between the symbol * @param pSymbol Where to return the symbol info. * @param phMod Where to return the module handle. Optional. * Query a symbol by address. * @returns IPRT status code. See RTDbgModSymbolAddrA for more specific ones. * @retval VERR_INVALID_HANDLE if hDbgAs is invalid. * @retval VERR_NOT_FOUND if the address couldn't be mapped to a module. * @retval VERR_INVALID_PARAMETER if incorrect flags. * @param hDbgAs The address space handle. * @param Addr The address which closest symbol is requested. * @param fFlags Symbol search flags, see RTDBGSYMADDR_FLAGS_XXX. * @param poffDisp Where to return the distance between the symbol * @param ppSymInfo Where to return the pointer to the allocated symbol * info. Always set. Free with RTDbgSymbolFree. * @param phMod Where to return the module handle. Optional. * Query a symbol by name. * @returns IPRT status code. * @retval VERR_SYMBOL_NOT_FOUND if not found. * @param hDbgAs The address space handle. * @param pszSymbol The symbol name. It is possible to limit the scope * of the search by prefixing the symbol with a module * name pattern followed by a bang (!) character. * RTStrSimplePatternNMatch is used for the matching. * @param pSymbol Where to return the symbol info. * @param phMod Where to return the module handle. Optional. * Query a symbol by name, allocating the returned symbol structure. * @returns IPRT status code. * @retval VERR_SYMBOL_NOT_FOUND if not found. * @param hDbgAs The address space handle. * @param pszSymbol The symbol name. See RTDbgAsSymbolByName for more. * @param ppSymbol Where to return the pointer to the allocated * symbol info. Always set. Free with RTDbgSymbolFree. * @param phMod Where to return the module handle. Optional. * Query a line number by address. * @returns IPRT status code. See RTDbgModSymbolAddrA for more specific ones. * @retval VERR_INVALID_HANDLE if hDbgAs is invalid. * @retval VERR_NOT_FOUND if the address couldn't be mapped to a module. * @param hDbgAs The address space handle. * @param Addr The address which closest symbol is requested. * @param poffDisp Where to return the distance between the line * @param pLine Where to return the line number information. * Adds a line number to a module in the address space. * @returns IPRT status code. See RTDbgModSymbolAdd for more specific ones. * @retval VERR_INVALID_HANDLE if hDbgAs is invalid. * @retval VERR_NOT_FOUND if no module was found at the specified address. * @retval VERR_NOT_SUPPORTED if the module interpret doesn't support adding * @param hDbgAs The address space handle. * @param pszFile The file name. * @param uLineNo The line number. * @param Addr The address of the symbol. * @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. * Query a line number by address. * @returns IPRT status code. See RTDbgModSymbolAddrA for more specific ones. * @retval VERR_INVALID_HANDLE if hDbgAs is invalid. * @retval VERR_NOT_FOUND if the address couldn't be mapped to a module. * @param hDbgAs The address space handle. * @param Addr The address which closest symbol is requested. * @param poffDisp Where to return the distance between the line * @param pLine Where to return the line number information. * Query a line number by address. * @returns IPRT status code. See RTDbgModSymbolAddrA for more specific ones. * @retval VERR_INVALID_HANDLE if hDbgAs is invalid. * @retval VERR_NOT_FOUND if the address couldn't be mapped to a module. * @param hDbgAs The address space handle. * @param Addr The address which closest symbol is requested. * @param poffDisp Where to return the distance between the line * @param ppLine Where to return the pointer to the allocated line * number info. Always set. Free with RTDbgLineFree. /** @todo Missing some bits here. */ /** @defgroup grp_rt_dbgmod RTDbgMod - Debug Module Interpreter * 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. * 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 * @remarks Will not take any locks. * @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 * @param hDbgMod The module handle. * @param uRva The image relative address to convert. * @param poffSeg Where to return the segment offset. Optional. * 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. * 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 * 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 * @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. * Gets the number of segments in the module. * This is can be used to determine the range which can be passed to * RTDbgModSegmentByIndex and derivates. * @returns The segment relative address. * NIL_RTDBGSEGIDX if the handle is invalid. * @param hDbgMod The module handle. * 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. * 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 * @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. * 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 * @param hDbgMod The module handle. * @param iSeg The segment index. No special segment indexes * 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 * @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 * @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 * 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 * @param hDbgMod The module handle. * 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. * 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 * 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 * @retval VERR_INVALID_PARAMETER if incorrect flags. * @param hDbgMod The module handle. * @param iSeg The segment number. * @param off The offset into the segment. * @param fFlags Symbol search flags, see RTDBGSYMADDR_FLAGS_XXX. * @param poffDisp Where to store the distance between the * specified address and the returned symbol. * @param pSymInfo Where to store the symbol information. * 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 * @retval VERR_NO_MEMORY if RTDbgSymbolAlloc fails. * @retval VERR_INVALID_PARAMETER if incorrect flags. * @param hDbgMod The module handle. * @param iSeg The segment index. * @param off The offset into the segment. * @param fFlags Symbol search flags, see RTDBGSYMADDR_FLAGS_XXX. * @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 * 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 * @param hDbgMod The module handle. * @param pszSymbol The symbol name. * @param pSymInfo Where to store the symbol information. * 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 * @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 * 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 * @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 * @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. * 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 * @param hDbgMod The module handle. * 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 * @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 * 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 * @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 * 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 * @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. * @param pLineInfo Where to store the line number information. * 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 * @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. * @param ppLineInfo Where to store the pointer to the returned line * number information. Always set. Free with /** @name Kernel Debug Info API * This is a specialized API for obtaining symbols and structure information * about the running kernel. It is relatively OS specific. Its purpose and * operation is doesn't map all that well onto RTDbgMod, so a few dedicated * functions was created for it. /** Handle to the kernel debug info. */ /** Pointer to a kernel debug info handle. */ /** Nil kernel debug info handle. */ * Opens the kernel debug info. * @returns IPRT status code. Can fail for any number of reasons. * @param phKrnlInfo Where to return the kernel debug info handle on * @param fFlags Flags reserved for future use. Must be zero. * Retains a reference to the kernel debug info handle. * @returns New reference count, UINT32_MAX on invalid handle (asserted). * @param hKrnlInfo The kernel info handle. * Releases a reference to the kernel debug info handle, destroying it when the * @returns New reference count, UINT32_MAX on invalid handle (asserted). * @param hKrnlInfo The kernel info handle. NIL_RTDBGKRNLINFO is * Queries the offset (in bytes) of a member of a kernel structure. * @returns IPRT status code. * @retval VINF_SUCCESS and offset at @a poffMember. * @retval VERR_NOT_FOUND if the structure or the member was not found. * @retval VERR_INVALID_HANDLE if hKrnlInfo is bad. * @retval VERR_INVALID_POINTER if any of the pointers are bad. * @param hKrnlInfo The kernel info handle. * @param pszStructure The structure name. * @param pszMember The member name. * @param poffMember Where to return the offset. * Queries the value (usually the address) of a kernel symbol. * This may go looking for the symbol in other modules, in which case it will * always check the kernel symbol table first. * @returns IPRT status code. * @retval VINF_SUCCESS and value at @a ppvSymbol. * @retval VERR_SYMBOL_NOT_FOUND * @retval VERR_INVALID_HANDLE if hKrnlInfo is bad. * @retval VERR_INVALID_POINTER if any of the pointers are bad. * @param hKrnlInfo The kernel info handle. * @param pszModule Reserved for future extensions. Pass NULL. * @param pszSymbol The C name of the symbol. * @param ppvSymbol Where to return the symbol value, passing NULL is * OK. This may be modified even on failure, in * particular, it will be set to NULL when * VERR_SYMBOL_NOT_FOUND is returned.