ldr.h revision abe1b07126bb9f5644b2ad8424534c2d1e97a66c
* Loads a dynamic load library (/shared object) image file using native * The filename will be appended the default DLL/SO extension of * the platform if it have been omitted. This means that it's not * possible to load DLLs/SOs with no extension using this interface, * but that's not a bad tradeoff. * If no path is specified in the filename, the OS will usually search it's library * path to find the image file. * @returns iprt status code. * @param pszFilename Image filename. * @param phLdrMod Where to store the handle to the loader module. * Loads a dynamic load library (/shared object) image file using native * The filename will be appended the default DLL/SO extension of * the platform if it have been omitted. This means that it's not * possible to load DLLs/SOs with no extension using this interface, * but that's not a bad tradeoff. * If no path is specified in the filename, the OS will usually search it's library * path to find the image file. * @returns iprt status code. * @param pszFilename Image filename. * @param phLdrMod Where to store the handle to the loader module. * @param fFlags See RTLDRLOAD_FLAGS_XXX. * @param pErrInfo Where to return extended error information. Optional. /** @defgroup RTLDRLOAD_FLAGS_XXX RTLdrLoadEx flags. /** Symbols defined in this library are not made available to resolve * references in subsequently loaded libraries (default). */ /** Symbols defined in this library will be made available for symbol * resolution of subsequently loaded libraries. */ /** The mask of valid flag bits. */ * Loads a dynamic load library (/shared object) image file residing in the * RTPathAppPrivateArch() directory. * Suffix is not required. * @returns iprt status code. * @param pszFilename Image filename. No path. * @param phLdrMod Where to store the handle to the loaded module. * Image architecuture specifier for RTLdrOpenEx. /** The host architecture. */ /** AMD64 (64-bit x86 if you like). */ /** End of the valid values. */ /** Make sure the type is a full 32-bit. */ /** Pointer to a RTLDRARCH. */ /** @name RTLDR_O_XXX - RTLdrOpen flags. /** Open for debugging or introspection reasons. * This will skip a few of the stricter validations when loading images. */ /** Mask of valid flags. */ * Open a binary image file, extended version. * @returns iprt status code. * @param pszFilename Image filename. * @param fFlags Valid RTLDR_O_XXX combination. * @param enmArch CPU architecture specifier for the image to be loaded. * @param phLdrMod Where to store the handle to the loader module. * Opens a binary image file using kLdr. * @returns iprt status code. * @param pszFilename Image filename. * @param phLdrMod Where to store the handle to the loaded module. * @param fFlags Valid RTLDR_O_XXX combination. * @param enmArch CPU architecture specifier for the image to be loaded. * @remark Primarily for testing the loader. * Called to read @a cb bytes at @a off into @a pvBuf. * @returns IPRT status code * @param pvBuf The output buffer. * @param cb The number of bytes to read. * @param off Where to start reading. * @param pvUser The user parameter. /** Pointer to a RTLdrOpenInMemory reader callback. */ * Called to when the module is unloaded (or done loading) to release resources * associated with it (@a pvUser). * @returns IPRT status code * @param pvUser The user parameter. /** Pointer to a RTLdrOpenInMemory destructor callback. */ * Open a in-memory image or an image with a custom reader callback. * @returns IPRT status code. * @param pszName The image name. * @param fFlags Valid RTLDR_O_XXX combination. * @param enmArch CPU architecture specifier for the image to be loaded. * @param cbImage The size of the image (fake file). * @param pfnRead The read function. If NULL is passed in, a default * reader function is provided that assumes @a pvUser * points to the raw image bits, at least @a cbImage of * @param pfnDtor The destructor function. If NULL is passed, a default * destructor will be provided that passes @a pvUser to * @param pvUser The user argument or, if any of the callbacks are NULL, * a pointer to a memory block. * @param phLdrMod Where to return the module handle. * @remarks With the exception of invalid @a pfnDtor and/or @a pvUser * parameters, the pfnDtor methods (or the default one if NULL) will * always be invoked. The destruction of pvUser is entirely in the * hands of this method once it's called. * Closes a loader module handle. * The handle can be obtained using any of the RTLdrLoad(), RTLdrOpen() * and RTLdrOpenInMemory() functions. * @returns iprt status code. * @param hLdrMod The loader module handle. * Gets the address of a named exported symbol. * @returns iprt status code. * @param hLdrMod The loader module handle. * @param pszSymbol Symbol name. * @param ppvValue Where to store the symbol value. Note that this is restricted to the * pointer size used on the host! * Gets the address of a named exported symbol. * This function differs from the plain one in that it can deal with * both GC and HC address sizes, and that it can calculate the symbol * value relative to any given base address. * @returns iprt status code. * @param hLdrMod The loader module handle. * @param pvBits Optional pointer to the loaded image. * Set this to NULL if no RTLdrGetBits() processed image bits are available. * Not supported for RTLdrLoad() images. * @param BaseAddress Image load address. * Not supported for RTLdrLoad() images. * @param pszSymbol Symbol name. * @param pValue Where to store the symbol value. * Gets the size of the loaded image. * This is not necessarily available for images that has been loaded using * @returns image size (in bytes). * @returns ~(size_t)0 on if not available. * @param hLdrMod Handle to the loader module. * Resolve an external symbol during RTLdrGetBits(). * @returns iprt status code. * @param hLdrMod The loader module handle. * @param pszModule Module name. * @param pszSymbol Symbol name, NULL if uSymbol should be used. * @param uSymbol Symbol ordinal, ~0 if pszSymbol should be used. * @param pValue Where to store the symbol value (address). * @param pvUser User argument. /** Pointer to a FNRTLDRIMPORT() callback function. */ * Loads the image into a buffer provided by the user and applies fixups * for the given base address. * @returns iprt status code. * @param hLdrMod The load module handle. * @param pvBits Where to put the bits. * Must be as large as RTLdrSize() suggests. * @param BaseAddress The base address. * @param pfnGetImport Callback function for resolving imports one by one. * @param pvUser User argument for the callback. * @remark Not supported for RTLdrLoad() images. * Relocates bits after getting them. * Useful for code which moves around a bit. * @returns iprt status code. * @param hLdrMod The loader module handle. * @param pvBits Where the image bits are. * Must have been passed to RTLdrGetBits(). * @param NewBaseAddress The new base address. * @param OldBaseAddress The old base address. * @param pfnGetImport Callback function for resolving imports one by one. * @param pvUser User argument for the callback. * @remark Not supported for RTLdrLoad() images. * Enumeration callback function used by RTLdrEnumSymbols(). * @returns iprt status code. Failure will stop the enumeration. * @param hLdrMod The loader module handle. * @param pszSymbol Symbol name. NULL if ordinal only. * @param uSymbol Symbol ordinal, ~0 if not used. * @param Value Symbol value. * @param pvUser The user argument specified to RTLdrEnumSymbols(). /** Pointer to a RTLDRENUMSYMS() callback function. */ * Enumerates all symbols in a module. * @returns iprt status code. * @param hLdrMod The loader module handle. * @param fFlags Flags indicating what to return and such. * @param pvBits Optional pointer to the loaded image. (RTLDR_ENUM_SYMBOL_FLAGS_*) * Set this to NULL if no RTLdrGetBits() processed image bits are available. * @param BaseAddress Image load address. * @param pfnCallback Callback function. * @param pvUser User argument for the callback. * @remark Not supported for RTLdrLoad() images. /** @name RTLdrEnumSymbols flags. /** Returns ALL kinds of symbols. The default is to only return public/exported symbols. */ /** Ignore forwarders (for use with RTLDR_ENUM_SYMBOL_FLAGS_ALL). */ * Debug info type (as far the loader can tell). /** The invalid 0 value. */ /** Unknown debug info format. */ /** Debug With Arbitrary Record Format (DWARF). */ /** Debug With Arbitrary Record Format (DWARF), in external file (DWO). */ /** Microsoft Codeview debug info. */ /** Microsoft Codeview debug info, in external v2.0+ program database (PDB). */ /** Microsoft Codeview debug info, in external v7.0+ program database (PDB). */ /** Microsoft Codeview debug info, in external file (DBG). */ /** Watcom debug info. */ /** IBM High Level Language debug info.. */ /** The end of the valid debug info values (exclusive). */ /** Blow the type up to 32-bits. */ * Debug info details for the enumeration callback. /** The kind of debug info. */ /** The debug info ordinal number / id. */ /** The file offset *if* this type has one specific location in the executable * image file. This is -1 if there isn't any specific file location. */ /** The link address of the debug info if it's loadable. NIL_RTLDRADDR if not /** The size of the debug information. -1 is used if this isn't applicable.*/ /** This is set if the debug information is found in an external file. NULL * if no external file involved. * @note Putting it outside the union to allow lazy callback implementation. */ /** Type (enmType) specific information. */ /** RTLDRDBGINFOTYPE_DWARF */ /** RTLDRDBGINFOTYPE_DWARF_DWO */ /** The CRC32 of the external file. */ /** RTLDRDBGINFOTYPE_CODEVIEW_PDB20, RTLDRDBGINFOTYPE_CODEVIEW_DBG */ /** The PE image size. */ /** The major version from the entry. */ /** The minor version from the entry. */ /** RTLDRDBGINFOTYPE_CODEVIEW_DBG */ /** The PE image size. */ /** RTLDRDBGINFOTYPE_CODEVIEW_PDB20*/ /** The PE image size. */ /** RTLDRDBGINFOTYPE_CODEVIEW_PDB70 */ /** The PE image size. */ /** Pointer to debug info details. */ /** Pointer to read only debug info details. */ * Debug info enumerator callback. * @returns VINF_SUCCESS to continue the enumeration. Any other status code * will cause RTLdrEnumDbgInfo to immediately return with that status. * @param hLdrMod The module handle. * @param pDbgInfo Pointer to a read only structure with the details. * @param pvUser The user parameter specified to RTLdrEnumDbgInfo. /** Pointer to a debug info enumerator callback. */ * Enumerate the debug info contained in the executable image. * @returns IPRT status code or whatever pfnCallback returns. * @param hLdrMod The module handle. * @param pvBits Optional pointer to bits returned by * RTLdrGetBits(). This can be used by some module * interpreters to reduce memory consumption. * @param pfnCallback The callback function. * @param pvUser The user argument. /** The segment name. (Might not be zero terminated!) */ /** The length of the segment name. */ /** The flat selector to use for the segment (i.e. data/code). * Primarily a way for the user to specify selectors for the LX/LE and NE interpreters. */ /** The 16-bit selector to use for the segment. * Primarily a way for the user to specify selectors for the LX/LE and NE interpreters. */ /** The segment protection (RTMEM_PROT_XXX). */ /** The size of the segment. */ /** The required segment alignment. * The to 0 if the segment isn't supposed to be mapped. */ * Set to NIL_RTLDRADDR if the segment isn't supposed to be mapped or if * the image doesn't have link addresses. */ /** File offset of the segment. * Set to -1 if no file backing (like BSS). */ /** Size of the file bits of the segment. * Set to -1 if no file backing (like BSS). */ /** The relative virtual address when mapped. * Set to NIL_RTLDRADDR if the segment isn't supposed to be mapped. */ /** The size of the segment including the alignment gap up to the next segment when mapped. * This is set to NIL_RTLDRADDR if not implemented. */ /** Pointer to a loader segment. */ /** Pointer to a read only loader segment. */ /** The segment is 16-bit. When not set the default of the target architecture is assumed. */ /** The segment requires a 16-bit selector alias. (OS/2) */ /** Conforming segment (x86 weirdness). (OS/2) */ /** IOPL (ring-2) segment. (OS/2) */ * Segment enumerator callback. * @returns VINF_SUCCESS to continue the enumeration. Any other status code * will cause RTLdrEnumSegments to immediately return with that * @param hLdrMod The module handle. * @param pSeg The segment information. * @param pvUser The user parameter specified to RTLdrEnumSegments. /** Pointer to a segment enumerator callback. */ * Enumerate the debug info contained in the executable image. * @returns IPRT status code or whatever pfnCallback returns. * @param hLdrMod The module handle. * @param pfnCallback The callback function. * @param pvUser The user argument. * Converts a link address to a segment:offset address. * @returns IPRT status code. * @param hLdrMod The module handle. * @param LinkAddress The link address to convert. * @param piSeg Where to return the segment index. * @param poffSeg Where to return the segment offset. * Converts a link address to an image relative virtual address (RVA). * @returns IPRT status code. * @param hLdrMod The module handle. * @param LinkAddress The link address to convert. * @param pRva Where to return the RVA. * Converts an image relative virtual address (RVA) to a segment:offset. * @returns IPRT status code. * @param hLdrMod The module handle. * @param Rva The link address to convert. * @param piSeg Where to return the segment index. * @param poffSeg Where to return the segment offset. * Converts a segment:offset into an image relative virtual address (RVA). * @returns IPRT status code. * @param hLdrMod The module handle. * @param iSeg The segment index. * @param offSeg The segment offset. * @param pRva Where to return the RVA.