VirtualBox

Changeset 20801 in vbox for trunk/include


Ignore:
Timestamp:
Jun 23, 2009 12:10:32 AM (16 years ago)
Author:
vboxsync
svn:sync-xref-src-repo-rev:
48928
Message:

IPRT: The rest of the basic RTDbgMod code.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/include/iprt/dbg.h

    r20800 r20801  
    755755RTDECL(RTUINTPTR)   RTDbgModSegmentRva(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg);
    756756
    757 RTDECL(int)         RTDbgModSymbolAdd(RTDBGMOD hDbgMod, const char *pszSymbol, RTDBGSEGIDX iSeg, RTUINTPTR off, RTUINTPTR cb, uint32_t fFlags, uint32_t *piOrdinal);
     757
     758/**
     759 * Adds a line number to the module.
     760 *
     761 * @returns IPRT status code.
     762 * @retval  VERR_NOT_SUPPORTED if the module interpret doesn't support adding
     763 *          custom symbols. This is a common place occurance.
     764 * @retval  VERR_INVALID_HANDLE if hDbgMod is invalid.
     765 * @retval  VERR_DBG_SYMBOL_NAME_OUT_OF_RANGE if the symbol name is too long or
     766 *          short.
     767 * @retval  VERR_DBG_INVALID_RVA if an image relative address is specified and
     768 *          it's not inside any of the segments defined by the module.
     769 * @retval  VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
     770 * @retval  VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
     771 *          end of the segment.
     772 * @retval  VERR_DBG_ADDRESS_WRAP if off+cb wraps around.
     773 * @retval  VERR_INVALID_PARAMETER if the symbol flags sets undefined bits.
     774 *
     775 * @param   hDbgMod         The module handle.
     776 * @param   pszSymbol       The symbol name.
     777 * @param   iSeg            The segment index.
     778 * @param   off             The segment offset.
     779 * @param   cb              The size of the symbol. Can be zero, although this
     780 *                          may depend somewhat on the debug interpreter.
     781 * @param   fFlags          Symbol flags. Reserved for the future, MBZ.
     782 * @param   piOrdinal       Where to return the symbol ordinal on success. If
     783 *                          the interpreter doesn't do ordinals, this will be set to
     784 *                          UINT32_MAX. Optional.
     785 */
     786RTDECL(int)         RTDbgModSymbolAdd(RTDBGMOD hDbgMod, const char *pszSymbol, RTDBGSEGIDX iSeg, RTUINTPTR off,
     787                                      RTUINTPTR cb, uint32_t fFlags, uint32_t *piOrdinal);
     788
     789/**
     790 * Gets the symbol count.
     791 *
     792 * This can be used together wtih RTDbgModSymbolByOrdinal or
     793 * RTDbgModSymbolByOrdinalA to enumerate all the symbols.
     794 *
     795 * @returns The number of symbols in the module.
     796 *          UINT32_MAX is returned if the module handle is invalid or some other
     797 *          error occurs.
     798 *
     799 * @param   hDbgMod             The module handle.
     800 */
    758801RTDECL(uint32_t)    RTDbgModSymbolCount(RTDBGMOD hDbgMod);
     802
     803/**
     804 * Queries symbol information by ordinal number.
     805 *
     806 * @returns IPRT status code.
     807 * @retval  VERR_SYMBOL_NOT_FOUND if there is no symbol at the given number.
     808 * @retval  VERR_DBG_NO_SYMBOLS if there aren't any symbols.
     809 * @retval  VERR_INVALID_HANDLE if hDbgMod is invalid.
     810 * @retval  VERR_NOT_SUPPORTED if lookup by ordinal is not supported.
     811 *
     812 * @param   hDbgMod             The module handle.
     813 * @param   iOrdinal            The symbol ordinal number. 0-based. The highest
     814 *                              number is RTDbgModSymbolCount() - 1.
     815 * @param   pSymInfo            Where to store the symbol information.
     816 */
    759817RTDECL(int)         RTDbgModSymbolByOrdinal(RTDBGMOD hDbgMod, uint32_t iOrdinal, PRTDBGSYMBOL pSymInfo);
     818
     819/**
     820 * Queries symbol information by ordinal number.
     821 *
     822 * @returns IPRT status code.
     823 * @retval  VERR_DBG_NO_SYMBOLS if there aren't any symbols.
     824 * @retval  VERR_NOT_SUPPORTED if lookup by ordinal is not supported.
     825 * @retval  VERR_SYMBOL_NOT_FOUND if there is no symbol at the given number.
     826 * @retval  VERR_NO_MEMORY if RTDbgSymbolAlloc fails.
     827 *
     828 * @param   hDbgMod             The module handle.
     829 * @param   iOrdinal            The symbol ordinal number. 0-based. The highest
     830 *                              number is RTDbgModSymbolCount() - 1.
     831 * @param   ppSymInfo           Where to store the pointer to the returned
     832 *                              symbol information. Always set. Free with
     833 *                              RTDbgSymbolFree.
     834 */
    760835RTDECL(int)         RTDbgModSymbolByOrdinalA(RTDBGMOD hDbgMod, uint32_t iOrdinal, PRTDBGSYMBOL *ppSymInfo);
     836
     837/**
     838 * Queries symbol information by address.
     839 *
     840 * The returned symbol is what the debug info interpreter consideres the symbol
     841 * most applicable to the specified address. This usually means a symbol with an
     842 * address equal or lower than the requested.
     843 *
     844 * @returns IPRT status code.
     845 * @retval  VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
     846 * @retval  VERR_DBG_NO_SYMBOLS if there aren't any symbols.
     847 * @retval  VERR_INVALID_HANDLE if hDbgMod is invalid.
     848 * @retval  VERR_DBG_INVALID_RVA if an image relative address is specified and
     849 *          it's not inside any of the segments defined by the module.
     850 * @retval  VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
     851 * @retval  VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
     852 *          end of the segment.
     853 *
     854 * @param   hDbgMod             The module handle.
     855 * @param   iSeg                The segment number.
     856 * @param   off                 The offset into the segment.
     857 * @param   poffDisp            Where to store the distance between the
     858 *                              specified address and the returned symbol.
     859 *                              Optional.
     860 * @param   pSymInfo            Where to store the symbol information.
     861 */
    761862RTDECL(int)         RTDbgModSymbolByAddr(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, PRTINTPTR poffDisp, PRTDBGSYMBOL pSymInfo);
     863
     864/**
     865 * Queries symbol information by address.
     866 *
     867 * The returned symbol is what the debug info interpreter consideres the symbol
     868 * most applicable to the specified address. This usually means a symbol with an
     869 * address equal or lower than the requested.
     870 *
     871 * @returns IPRT status code.
     872 * @retval  VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
     873 * @retval  VERR_DBG_NO_SYMBOLS if there aren't any symbols.
     874 * @retval  VERR_INVALID_HANDLE if hDbgMod is invalid.
     875 * @retval  VERR_DBG_INVALID_RVA if an image relative address is specified and
     876 *          it's not inside any of the segments defined by the module.
     877 * @retval  VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
     878 * @retval  VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
     879 *          end of the segment.
     880 * @retval  VERR_NO_MEMORY if RTDbgSymbolAlloc fails.
     881 *
     882 * @param   hDbgMod             The module handle.
     883 * @param   iSeg                The segment index.
     884 * @param   off                 The offset into the segment.
     885 * @param   poffDisp            Where to store the distance between the
     886 *                              specified address and the returned symbol. Optional.
     887 * @param   ppSymInfo           Where to store the pointer to the returned
     888 *                              symbol information. Always set. Free with
     889 *                              RTDbgSymbolFree.
     890 */
    762891RTDECL(int)         RTDbgModSymbolByAddrA(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, PRTINTPTR poffDisp, PRTDBGSYMBOL *ppSymInfo);
     892
     893/**
     894 * Queries symbol information by symbol name.
     895 *
     896 * @returns IPRT status code.
     897 * @retval  VERR_DBG_NO_SYMBOLS if there aren't any symbols.
     898 * @retval  VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
     899 * @retval  VERR_DBG_SYMBOL_NAME_OUT_OF_RANGE if the symbol name is too long or
     900 *          short.
     901 *
     902 * @param   hDbgMod             The module handle.
     903 * @param   pszSymbol           The symbol name.
     904 * @param   pSymInfo            Where to store the symbol information.
     905 */
    763906RTDECL(int)         RTDbgModSymbolByName(RTDBGMOD hDbgMod, const char *pszSymbol, PRTDBGSYMBOL pSymInfo);
     907
     908/**
     909 * Queries symbol information by symbol name.
     910 *
     911 * @returns IPRT status code.
     912 * @retval  VERR_DBG_NO_SYMBOLS if there aren't any symbols.
     913 * @retval  VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
     914 * @retval  VERR_DBG_SYMBOL_NAME_OUT_OF_RANGE if the symbol name is too long or
     915 *          short.
     916 * @retval  VERR_NO_MEMORY if RTDbgSymbolAlloc fails.
     917 *
     918 * @param   hDbgMod             The module handle.
     919 * @param   pszSymbol           The symbol name.
     920 * @param   ppSymInfo           Where to store the pointer to the returned
     921 *                              symbol information. Always set. Free with
     922 *                              RTDbgSymbolFree.
     923 */
    764924RTDECL(int)         RTDbgModSymbolByNameA(RTDBGMOD hDbgMod, const char *pszSymbol, PRTDBGSYMBOL *ppSymInfo);
    765925
    766 RTDECL(int)         RTDbgModLineAdd(RTDBGMOD hDbgMod, const char *pszFile, uint32_t uLineNo, RTDBGSEGIDX iSeg, RTUINTPTR off, uint32_t *piOrdinal);
     926/**
     927 * Adds a line number to the module.
     928 *
     929 * @returns IPRT status code.
     930 * @retval  VERR_NOT_SUPPORTED if the module interpret doesn't support adding
     931 *          custom symbols. This should be consider a normal response.
     932 * @retval  VERR_INVALID_HANDLE if hDbgMod is invalid.
     933 * @retval  VERR_DBG_FILE_NAME_OUT_OF_RANGE if the file name is too longer or
     934 *          empty.
     935 * @retval  VERR_DBG_INVALID_RVA if an image relative address is specified and
     936 *          it's not inside any of the segments defined by the module.
     937 * @retval  VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
     938 * @retval  VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
     939 *          end of the segment.
     940 * @retval  VERR_INVALID_PARAMETER if the line number flags sets undefined bits.
     941 *
     942 * @param   hDbgMod             The module handle.
     943 * @param   pszFile             The file name.
     944 * @param   uLineNo             The line number.
     945 * @param   iSeg                The segment index.
     946 * @param   off                 The segment offset.
     947 * @param   piOrdinal           Where to return the line number ordinal on
     948 *                              success. If  the interpreter doesn't do ordinals,
     949 *                              this will be set to UINT32_MAX. Optional.
     950 */
     951RTDECL(int)         RTDbgModLineAdd(RTDBGMOD hDbgMod, const char *pszFile, uint32_t uLineNo,
     952                                    RTDBGSEGIDX iSeg, RTUINTPTR off, uint32_t *piOrdinal);
     953
     954/**
     955 * Gets the line number count.
     956 *
     957 * This can be used together wtih RTDbgModLineByOrdinal or RTDbgModSymbolByLineA
     958 * to enumerate all the line number information.
     959 *
     960 * @returns The number of line numbers in the module.
     961 *          UINT32_MAX is returned if the module handle is invalid or some other
     962 *          error occurs.
     963 *
     964 * @param   hDbgMod             The module handle.
     965 */
    767966RTDECL(uint32_t)    RTDbgModLineCount(RTDBGMOD hDbgMod);
    768 RTDECL(int)         RTDbgModLineByOrdinal(RTDBGMOD hDbgMod, uint32_t iOrdinal, PRTDBGLINE pLine);
    769 RTDECL(int)         RTDbgModLineByOrdinalA(RTDBGMOD hDbgMod, uint32_t iOrdinal, PRTDBGLINE *ppLine);
    770 RTDECL(int)         RTDbgModLineByAddr(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, PRTINTPTR poffDisp, PRTDBGLINE pLine);
    771 RTDECL(int)         RTDbgModLineByAddrA(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, PRTINTPTR poffDisp, PRTDBGLINE *ppLine);
     967
     968/**
     969 * Queries line number information by ordinal number.
     970 *
     971 * This can be used to enumerate the line numbers for the module. Use
     972 * RTDbgModLineCount() to figure the end of the ordinals.
     973 *
     974 * @returns IPRT status code.
     975 * @retval  VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
     976 * @retval  VERR_DBG_LINE_NOT_FOUND if there is no line number with that
     977 *          ordinal.
     978 * @retval  VERR_INVALID_HANDLE if hDbgMod is invalid.
     979
     980 * @param   hDbgMod             The module handle.
     981 * @param   iOrdinal            The line number ordinal number.
     982 * @param   pLineInfo           Where to store the information about the line
     983 *                              number.
     984 */
     985RTDECL(int)         RTDbgModLineByOrdinal(RTDBGMOD hDbgMod, uint32_t iOrdinal, PRTDBGLINE pLineInfo);
     986
     987/**
     988 * Queries line number information by ordinal number.
     989 *
     990 * This can be used to enumerate the line numbers for the module. Use
     991 * RTDbgModLineCount() to figure the end of the ordinals.
     992 *
     993 * @returns IPRT status code.
     994 * @retval  VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
     995 * @retval  VERR_DBG_LINE_NOT_FOUND if there is no line number with that
     996 *          ordinal.
     997 * @retval  VERR_INVALID_HANDLE if hDbgMod is invalid.
     998 * @retval  VERR_NO_MEMORY if RTDbgLineAlloc fails.
     999 *
     1000 * @param   hDbgMod             The module handle.
     1001 * @param   iOrdinal            The line number ordinal number.
     1002 * @param   ppLineInfo          Where to store the pointer to the returned line
     1003 *                              number information. Always set. Free with
     1004 *                              RTDbgLineFree.
     1005 */
     1006RTDECL(int)         RTDbgModLineByOrdinalA(RTDBGMOD hDbgMod, uint32_t iOrdinal, PRTDBGLINE *ppLineInfo);
     1007
     1008/**
     1009 * Queries line number information by address.
     1010 *
     1011 * The returned line number is what the debug info interpreter consideres the
     1012 * one most applicable to the specified address. This usually means a line
     1013 * number with an address equal or lower than the requested.
     1014 *
     1015 * @returns IPRT status code.
     1016 * @retval  VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
     1017 * @retval  VERR_DBG_LINE_NOT_FOUND if no suitable line number was found.
     1018 * @retval  VERR_INVALID_HANDLE if hDbgMod is invalid.
     1019 * @retval  VERR_DBG_INVALID_RVA if an image relative address is specified and
     1020 *          it's not inside any of the segments defined by the module.
     1021 * @retval  VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
     1022 * @retval  VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
     1023 *          end of the segment.
     1024 *
     1025 * @param   hDbgMod             The module handle.
     1026 * @param   iSeg                The segment number.
     1027 * @param   off                 The offset into the segment.
     1028 * @param   poffDisp            Where to store the distance between the
     1029 *                              specified address and the returned symbol.
     1030 *                              Optional.
     1031 * @param   pSymInfo            Where to store the symbol information.
     1032 */
     1033RTDECL(int)         RTDbgModLineByAddr(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, PRTINTPTR poffDisp, PRTDBGLINE pLineInfo);
     1034
     1035/**
     1036 * Queries line number information by address.
     1037 *
     1038 * The returned line number is what the debug info interpreter consideres the
     1039 * one most applicable to the specified address. This usually means a line
     1040 * number with an address equal or lower than the requested.
     1041 *
     1042 * @returns IPRT status code.
     1043 * @retval  VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
     1044 * @retval  VERR_DBG_LINE_NOT_FOUND if no suitable line number was found.
     1045 * @retval  VERR_INVALID_HANDLE if hDbgMod is invalid.
     1046 * @retval  VERR_DBG_INVALID_RVA if an image relative address is specified and
     1047 *          it's not inside any of the segments defined by the module.
     1048 * @retval  VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
     1049 * @retval  VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
     1050 *          end of the segment.
     1051 * @retval  VERR_NO_MEMORY if RTDbgLineAlloc fails.
     1052 *
     1053 * @param   hDbgMod             The module handle.
     1054 * @param   iSeg                The segment number.
     1055 * @param   off                 The offset into the segment.
     1056 * @param   poffDisp            Where to store the distance between the
     1057 *                              specified address and the returned symbol.
     1058 *                              Optional.
     1059 * @param   ppLineInfo          Where to store the pointer to the returned line
     1060 *                              number information. Always set. Free with
     1061 *                              RTDbgLineFree.
     1062 */
     1063RTDECL(int)         RTDbgModLineByAddrA(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, PRTINTPTR poffDisp, PRTDBGLINE *ppLineInfo);
    7721064/** @} */
    7731065
Note: See TracChangeset for help on using the changeset viewer.

© 2025 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette