ldr.h revision 3ef0f8c1821a20af9d674b5aeb51aa7afc7e49e0
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * IPRT - Loader.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * Copyright (C) 2006-2007 Oracle Corporation
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * available from http://www.virtualbox.org. This file is free software;
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * you can redistribute it and/or modify it under the terms of the GNU
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * General Public License (GPL) as published by the Free Software
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * The contents of this file may alternatively be used under the terms
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * of the Common Development and Distribution License Version 1.0
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * VirtualBox OSE distribution, in which case the provisions of the
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * CDDL are applicable instead of those of the GPL.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * You may elect to license modified versions of this file under the
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * terms and conditions of either the GPL or the CDDL or both.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync/** @defgroup grp_ldr RTLdr - Loader
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @ingroup grp_rt
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * Gets the default file suffix for DLL/SO/DYLIB/whatever.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @returns The stuff (readonly).
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * Checks if a library is loadable or not.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * This may attempt load and unload the library.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @returns true/false accordingly.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param pszFilename Image filename.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsyncRTDECL(bool) RTLdrIsLoadable(const char *pszFilename);
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * Loads a dynamic load library (/shared object) image file using native
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * OS facilities.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * The filename will be appended the default DLL/SO extension of
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * the platform if it have been omitted. This means that it's not
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * possible to load DLLs/SOs with no extension using this interface,
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * but that's not a bad tradeoff.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * If no path is specified in the filename, the OS will usually search it's library
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * path to find the image file.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @returns iprt status code.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param pszFilename Image filename.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param phLdrMod Where to store the handle to the loader module.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsyncRTDECL(int) RTLdrLoad(const char *pszFilename, PRTLDRMOD phLdrMod);
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * Loads a dynamic load library (/shared object) image file using native
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * OS facilities.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * The filename will be appended the default DLL/SO extension of
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * the platform if it have been omitted. This means that it's not
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * possible to load DLLs/SOs with no extension using this interface,
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * but that's not a bad tradeoff.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * If no path is specified in the filename, the OS will usually search it's library
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * path to find the image file.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @returns iprt status code.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param pszFilename Image filename.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param phLdrMod Where to store the handle to the loader module.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param fFlags See RTLDRLOAD_FLAGS_XXX.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param pErrInfo Where to return extended error information. Optional.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsyncRTDECL(int) RTLdrLoadEx(const char *pszFilename, PRTLDRMOD phLdrMod, uint32_t fFlags, PRTERRINFO pErrInfo);
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync/** @defgroup RTLDRLOAD_FLAGS_XXX RTLdrLoadEx flags.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync/** Symbols defined in this library are not made available to resolve
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * references in subsequently loaded libraries (default). */
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync/** Symbols defined in this library will be made available for symbol
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * resolution of subsequently loaded libraries. */
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync/** The mask of valid flag bits. */
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync#define RTLDRLOAD_FLAGS_VALID_MASK UINT32_C(0x00000001)
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * Loads a dynamic load library (/shared object) image file residing in the
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * RTPathAppPrivateArch() directory.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * Suffix is not required.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @returns iprt status code.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param pszFilename Image filename. No path.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param phLdrMod Where to store the handle to the loaded module.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsyncRTDECL(int) RTLdrLoadAppPriv(const char *pszFilename, PRTLDRMOD phLdrMod);
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * Image architecuture specifier for RTLdrOpenEx.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync /** Whatever. */
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync /** The host architecture. */
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync /** 32-bit x86. */
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync /** AMD64 (64-bit x86 if you like). */
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync /** End of the valid values. */
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync /** Make sure the type is a full 32-bit. */
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync/** Pointer to a RTLDRARCH. */
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * Open a binary image file, extended version.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @returns iprt status code.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param pszFilename Image filename.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param fFlags Reserved, MBZ.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param enmArch CPU architecture specifier for the image to be loaded.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param phLdrMod Where to store the handle to the loader module.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsyncRTDECL(int) RTLdrOpen(const char *pszFilename, uint32_t fFlags, RTLDRARCH enmArch, PRTLDRMOD phLdrMod);
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * Opens a binary image file using kLdr.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @returns iprt status code.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param pszFilename Image filename.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param phLdrMod Where to store the handle to the loaded module.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param fFlags Reserved, MBZ.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param enmArch CPU architecture specifier for the image to be loaded.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @remark Primarily for testing the loader.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsyncRTDECL(int) RTLdrOpenkLdr(const char *pszFilename, uint32_t fFlags, RTLDRARCH enmArch, PRTLDRMOD phLdrMod);
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * What to expect and do with the bits passed to RTLdrOpenBits().
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync /** The usual invalid 0 entry. */
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync /** The bits are readonly and will never be changed. */
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync /** The bits are going to be changed and the loader will have to duplicate them
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * when opening the image. */
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync /** The bits are both the source and destination for the loader operation.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * This means that the loader may have to duplicate them prior to changing them. */
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync /** The end of the valid enums. This entry marks the
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * first invalid entry.. */
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * Open a binary image from in-memory bits.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @returns iprt status code.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param pvBits The start of the raw-image.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param cbBits The size of the raw-image.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param enmBits What to expect from the pvBits.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param pszLogName What to call the raw-image when logging.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * For RTLdrLoad and RTLdrOpen the filename is used for this.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param phLdrMod Where to store the handle to the loader module.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsyncRTDECL(int) RTLdrOpenBits(const void *pvBits, size_t cbBits, RTLDROPENBITS enmBits, const char *pszLogName, PRTLDRMOD phLdrMod);
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * Closes a loader module handle.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * The handle can be obtained using any of the RTLdrLoad(), RTLdrOpen()
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * and RTLdrOpenBits() functions.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @returns iprt status code.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param hLdrMod The loader module handle.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * Gets the address of a named exported symbol.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @returns iprt status code.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param hLdrMod The loader module handle.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param pszSymbol Symbol name.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param ppvValue Where to store the symbol value. Note that this is restricted to the
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * pointer size used on the host!
3331475701a5b12f98b3cfea07d5dca60072530fvboxsyncRTDECL(int) RTLdrGetSymbol(RTLDRMOD hLdrMod, const char *pszSymbol, void **ppvValue);
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * Gets the address of a named exported symbol.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * This function differs from the plain one in that it can deal with
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * both GC and HC address sizes, and that it can calculate the symbol
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * value relative to any given base address.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @returns iprt status code.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param hLdrMod The loader module handle.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param pvBits Optional pointer to the loaded image.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * Set this to NULL if no RTLdrGetBits() processed image bits are available.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * Not supported for RTLdrLoad() images.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param BaseAddress Image load address.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * Not supported for RTLdrLoad() images.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param pszSymbol Symbol name.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param pValue Where to store the symbol value.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsyncRTDECL(int) RTLdrGetSymbolEx(RTLDRMOD hLdrMod, const void *pvBits, RTUINTPTR BaseAddress, const char *pszSymbol, RTUINTPTR *pValue);
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * Gets the size of the loaded image.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * This is only supported for modules which has been opened using RTLdrOpen() and RTLdrOpenBits().
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @returns image size (in bytes).
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @returns ~(size_t)0 on if not opened by RTLdrOpen().
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param hLdrMod Handle to the loader module.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @remark Not supported for RTLdrLoad() images.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * Resolve an external symbol during RTLdrGetBits().
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @returns iprt status code.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param hLdrMod The loader module handle.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param pszModule Module name.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param pszSymbol Symbol name, NULL if uSymbol should be used.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param uSymbol Symbol ordinal, ~0 if pszSymbol should be used.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param pValue Where to store the symbol value (address).
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param pvUser User argument.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsynctypedef DECLCALLBACK(int) RTLDRIMPORT(RTLDRMOD hLdrMod, const char *pszModule, const char *pszSymbol, unsigned uSymbol, RTUINTPTR *pValue, void *pvUser);
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync/** Pointer to a FNRTLDRIMPORT() callback function. */
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * Loads the image into a buffer provided by the user and applies fixups
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * for the given base address.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @returns iprt status code.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param hLdrMod The load module handle.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param pvBits Where to put the bits.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * Must be as large as RTLdrSize() suggests.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param BaseAddress The base address.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param pfnGetImport Callback function for resolving imports one by one.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param pvUser User argument for the callback.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @remark Not supported for RTLdrLoad() images.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsyncRTDECL(int) RTLdrGetBits(RTLDRMOD hLdrMod, void *pvBits, RTUINTPTR BaseAddress, PFNRTLDRIMPORT pfnGetImport, void *pvUser);
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * Relocates bits after getting them.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * Useful for code which moves around a bit.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @returns iprt status code.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param hLdrMod The loader module handle.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param pvBits Where the image bits are.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * Must have been passed to RTLdrGetBits().
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param NewBaseAddress The new base address.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param OldBaseAddress The old base address.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param pfnGetImport Callback function for resolving imports one by one.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param pvUser User argument for the callback.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @remark Not supported for RTLdrLoad() images.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsyncRTDECL(int) RTLdrRelocate(RTLDRMOD hLdrMod, void *pvBits, RTUINTPTR NewBaseAddress, RTUINTPTR OldBaseAddress,
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * Enumeration callback function used by RTLdrEnumSymbols().
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @returns iprt status code. Failure will stop the enumeration.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param hLdrMod The loader module handle.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param pszSymbol Symbol name. NULL if ordinal only.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param uSymbol Symbol ordinal, ~0 if not used.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param Value Symbol value.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param pvUser The user argument specified to RTLdrEnumSymbols().
3331475701a5b12f98b3cfea07d5dca60072530fvboxsynctypedef DECLCALLBACK(int) RTLDRENUMSYMS(RTLDRMOD hLdrMod, const char *pszSymbol, unsigned uSymbol, RTUINTPTR Value, void *pvUser);
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync/** Pointer to a RTLDRENUMSYMS() callback function. */
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * Enumerates all symbols in a module.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @returns iprt status code.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param hLdrMod The loader module handle.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param fFlags Flags indicating what to return and such.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param pvBits Optional pointer to the loaded image. (RTLDR_ENUM_SYMBOL_FLAGS_*)
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * Set this to NULL if no RTLdrGetBits() processed image bits are available.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param BaseAddress Image load address.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param pfnCallback Callback function.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @param pvUser User argument for the callback.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync * @remark Not supported for RTLdrLoad() images.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsyncRTDECL(int) RTLdrEnumSymbols(RTLDRMOD hLdrMod, unsigned fFlags, const void *pvBits, RTUINTPTR BaseAddress, PFNRTLDRENUMSYMS pfnCallback, void *pvUser);
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync/** @name RTLdrEnumSymbols flags.
3331475701a5b12f98b3cfea07d5dca60072530fvboxsync/** Returns ALL kinds of symbols. The default is to only return public/exported symbols. */