include/iprt/ldr.h

   1 /** @file
   2  * IPRT - Loader.
   3  */
   4
   5 /*
   6  * Copyright (C) 2006-2024 Oracle and/or its affiliates.
   7  *
   8  * This file is part of VirtualBox base platform packages, as
   9  * available from https://www.virtualbox.org.
  10  *
  11  * This program is free software; you can redistribute it and/or
  12  * modify it under the terms of the GNU General Public License
  13  * as published by the Free Software Foundation, in version 3 of the
  14  * License.
  15  *
  16  * This program is distributed in the hope that it will be useful, but
  17  * WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  19  * General Public License for more details.
  20  *
  21  * You should have received a copy of the GNU General Public License
  22  * along with this program; if not, see <https://www.gnu.org/licenses>.
  23  *
  24  * The contents of this file may alternatively be used under the terms
  25  * of the Common Development and Distribution License Version 1.0
  26  * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
  27  * in the VirtualBox distribution, in which case the provisions of the
  28  * CDDL are applicable instead of those of the GPL.
  29  *
  30  * You may elect to license modified versions of this file under the
  31  * terms and conditions of either the GPL or the CDDL or both.
  32  *
  33  * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
  34  */
  35
  36 #ifndef IPRT_INCLUDED_ldr_h
  37 #define IPRT_INCLUDED_ldr_h
  38 #ifndef RT_WITHOUT_PRAGMA_ONCE
  39 # pragma once
  40 #endif
  41
  42 #include <iprt/cdefs.h>
  43 #include <iprt/types.h>
  44
  45
  46 /** @defgroup grp_ldr       RTLdr - Loader
  47  * @ingroup grp_rt
  48  * @{
  49  */
  50
  51
  52 RT_C_DECLS_BEGIN
  53
  54 /** Loader address (unsigned integer). */
  55 typedef RTUINTPTR           RTLDRADDR;
  56 /** Pointer to a loader address. */
  57 typedef RTLDRADDR          *PRTLDRADDR;
  58 /** Pointer to a const loader address. */
  59 typedef RTLDRADDR const    *PCRTLDRADDR;
  60 /** The max loader address value. */
  61 #define RTLDRADDR_MAX       RTUINTPTR_MAX
  62 /** NIL loader address value. */
  63 #define NIL_RTLDRADDR       RTLDRADDR_MAX
  64
  65
  66 /**
  67  * Loader module format.
  68  */
  69 typedef enum RTLDRFMT
  70 {
  71     /** The usual invalid 0 format. */
  72     RTLDRFMT_INVALID = 0,
  73     /** The native OS loader. */
  74     RTLDRFMT_NATIVE,
  75     /** The AOUT loader. */
  76     RTLDRFMT_AOUT,
  77     /** The ELF loader. */
  78     RTLDRFMT_ELF,
  79     /** The LX loader. */
  80     RTLDRFMT_LX,
  81     /** The Mach-O loader. */
  82     RTLDRFMT_MACHO,
  83     /** The PE loader. */
  84     RTLDRFMT_PE,
  85     /** The end of the valid format values (exclusive). */
  86     RTLDRFMT_END,
  87     /** Hack to blow the type up to 32-bit. */
  88     RTLDRFMT_32BIT_HACK = 0x7fffffff
  89 } RTLDRFMT;
  90
  91
  92 /**
  93  * Loader module type.
  94  */
  95 typedef enum RTLDRTYPE
  96 {
  97     /** The usual invalid 0 type. */
  98     RTLDRTYPE_INVALID = 0,
  99     /** Object file. */
 100     RTLDRTYPE_OBJECT,
 101     /** Executable module, fixed load address. */
 102     RTLDRTYPE_EXECUTABLE_FIXED,
 103     /** Executable module, relocatable, non-fixed load address. */
 104     RTLDRTYPE_EXECUTABLE_RELOCATABLE,
 105     /** Executable module, position independent code, non-fixed load address. */
 106     RTLDRTYPE_EXECUTABLE_PIC,
 107     /** Shared library, fixed load address.
 108      * Typically a system library. */
 109     RTLDRTYPE_SHARED_LIBRARY_FIXED,
 110     /** Shared library, relocatable, non-fixed load address. */
 111     RTLDRTYPE_SHARED_LIBRARY_RELOCATABLE,
 112     /** Shared library, position independent code, non-fixed load address. */
 113     RTLDRTYPE_SHARED_LIBRARY_PIC,
 114     /** DLL that contains no code or data only imports and exports. (Chiefly OS/2.) */
 115     RTLDRTYPE_FORWARDER_DLL,
 116     /** Core or dump. */
 117     RTLDRTYPE_CORE,
 118     /** Debug module (debug info with empty code & data segments). */
 119     RTLDRTYPE_DEBUG_INFO,
 120     /** The end of the valid types values (exclusive). */
 121     RTLDRTYPE_END,
 122     /** Hack to blow the type up to 32-bit. */
 123     RTLDRTYPE_32BIT_HACK = 0x7fffffff
 124 } RTLDRTYPE;
 125
 126
 127 /**
 128  * Loader endian indicator.
 129  */
 130 typedef enum RTLDRENDIAN
 131 {
 132     /** The usual invalid endian. */
 133     RTLDRENDIAN_INVALID,
 134     /** Little endian. */
 135     RTLDRENDIAN_LITTLE,
 136     /** Bit endian. */
 137     RTLDRENDIAN_BIG,
 138     /** Endianness doesn't have a meaning in the context. */
 139     RTLDRENDIAN_NA,
 140     /** The end of the valid endian values (exclusive). */
 141     RTLDRENDIAN_END,
 142     /** Hack to blow the type up to 32-bit. */
 143     RTLDRENDIAN_32BIT_HACK = 0x7fffffff
 144 } RTLDRENDIAN;
 145
 146
 147 /** Pointer to a loader reader instance. */
 148 typedef struct RTLDRREADER *PRTLDRREADER;
 149 /**
 150  * Loader image reader instance.
 151  *
 152  * @remarks The reader will typically have a larger structure wrapping this one
 153  *          for storing necessary instance variables.
 154  *
 155  *          The loader ASSUMES the caller serializes all access to the
 156  *          individual loader module handlers, thus no serialization is required
 157  *          when implementing this interface.
 158  */
 159 typedef struct RTLDRREADER
 160 {
 161     /** Magic value (RTLDRREADER_MAGIC). */
 162     uintptr_t           uMagic;
 163
 164     /**
 165      * Reads bytes at a give place in the raw image.
 166      *
 167      * @returns iprt status code.
 168      * @param   pReader     Pointer to the reader instance.
 169      * @param   pvBuf       Where to store the bits.
 170      * @param   cb          Number of bytes to read.
 171      * @param   off         Where to start reading relative to the start of the raw image.
 172      */
 173     DECLCALLBACKMEMBER(int, pfnRead,(PRTLDRREADER pReader, void *pvBuf, size_t cb, RTFOFF off));
 174
 175     /**
 176      * Tells end position of last read.
 177      *
 178      * @returns position relative to start of the raw image.
 179      * @param   pReader     Pointer to the reader instance.
 180      */
 181     DECLCALLBACKMEMBER(RTFOFF, pfnTell,(PRTLDRREADER pReader));
 182
 183     /**
 184      * Gets the size of the raw image bits.
 185      *
 186      * @returns size of raw image bits in bytes.
 187      * @param   pReader     Pointer to the reader instance.
 188      */
 189     DECLCALLBACKMEMBER(uint64_t, pfnSize,(PRTLDRREADER pReader));
 190
 191     /**
 192      * Map the bits into memory.
 193      *
 194      * The mapping will be freed upon calling pfnDestroy() if not pfnUnmap()
 195      * is called before that. The mapping is read only.
 196      *
 197      * @returns iprt status code.
 198      * @param   pReader     Pointer to the reader instance.
 199      * @param   ppvBits     Where to store the address of the memory mapping on success.
 200      *                      The size of the mapping can be obtained by calling pfnSize().
 201      */
 202     DECLCALLBACKMEMBER(int, pfnMap,(PRTLDRREADER pReader, const void **ppvBits));
 203
 204     /**
 205      * Unmap bits.
 206      *
 207      * @returns iprt status code.
 208      * @param   pReader     Pointer to the reader instance.
 209      * @param   pvBits      Memory pointer returned by pfnMap().
 210      */
 211     DECLCALLBACKMEMBER(int, pfnUnmap,(PRTLDRREADER pReader, const void *pvBits));
 212
 213     /**
 214      * Gets the most appropriate log name.
 215      *
 216      * @returns Pointer to readonly log name.
 217      * @param   pReader     Pointer to the reader instance.
 218      */
 219     DECLCALLBACKMEMBER(const char *, pfnLogName,(PRTLDRREADER pReader));
 220
 221     /**
 222      * Releases all resources associated with the reader instance.
 223      * The instance is invalid after this call returns.
 224      *
 225      * @returns iprt status code.
 226      * @param   pReader     Pointer to the reader instance.
 227      */
 228     DECLCALLBACKMEMBER(int, pfnDestroy,(PRTLDRREADER pReader));
 229 } RTLDRREADER;
 230
 231 /** Magic value for RTLDRREADER (Gordon Matthew Thomas Sumner / Sting). */
 232 #define RTLDRREADER_MAGIC   UINT32_C(0x19511002)
 233
 234
 235 /**
 236  * Gets the default file suffix for DLL/SO/DYLIB/whatever.
 237  *
 238  * @returns The stuff (readonly).
 239  */
 240 RTDECL(const char *) RTLdrGetSuff(void);
 241
 242 /**
 243  * Checks if a library is loadable or not.
 244  *
 245  * This may attempt load and unload the library.
 246  *
 247  * @returns true/false accordingly.
 248  * @param   pszFilename     Image filename.
 249  */
 250 RTDECL(bool) RTLdrIsLoadable(const char *pszFilename);
 251
 252 /**
 253  * Loads a dynamic load library (/shared object) image file using native
 254  * OS facilities.
 255  *
 256  * The filename will be appended the default DLL/SO extension of
 257  * the platform if it have been omitted. This means that it's not
 258  * possible to load DLLs/SOs with no extension using this interface,
 259  * but that's not a bad tradeoff.
 260  *
 261  * If no path is specified in the filename, the OS will usually search it's library
 262  * path to find the image file.
 263  *
 264  * @returns iprt status code.
 265  * @param   pszFilename Image filename.
 266  * @param   phLdrMod    Where to store the handle to the loader module.
 267  */
 268 RTDECL(int) RTLdrLoad(const char *pszFilename, PRTLDRMOD phLdrMod);
 269
 270 /**
 271  * Loads a dynamic load library (/shared object) image file using native
 272  * OS facilities.
 273  *
 274  * The filename will be appended the default DLL/SO extension of
 275  * the platform if it have been omitted. This means that it's not
 276  * possible to load DLLs/SOs with no extension using this interface,
 277  * but that's not a bad tradeoff.
 278  *
 279  * If no path is specified in the filename, the OS will usually search it's library
 280  * path to find the image file.
 281  *
 282  * @returns iprt status code.
 283  * @param   pszFilename Image filename.
 284  * @param   phLdrMod    Where to store the handle to the loader module.
 285  * @param   fFlags      See RTLDRLOAD_FLAGS_XXX.
 286  * @param   pErrInfo    Where to return extended error information. Optional.
 287  */
 288 RTDECL(int) RTLdrLoadEx(const char *pszFilename, PRTLDRMOD phLdrMod, uint32_t fFlags, PRTERRINFO pErrInfo);
 289
 290 /** @defgroup RTLDRLOAD_FLAGS_XXX Flags for RTLdrLoadEx, RTLdrLoadSystemEx and RTLdrGetSystemSymbolEx
 291  * @{ */
 292 /** Symbols defined in this library are not made available to resolve
 293  * references in subsequently loaded libraries (default). */
 294 #define RTLDRLOAD_FLAGS_LOCAL                   UINT32_C(0)
 295 /** Symbols defined in this library will be made available for symbol
 296  * resolution of subsequently loaded libraries. */
 297 #define RTLDRLOAD_FLAGS_GLOBAL                  RT_BIT_32(0)
 298 /** Do not unload the library upon RTLdrClose. (For system libs.) */
 299 #define RTLDRLOAD_FLAGS_NO_UNLOAD               RT_BIT_32(1)
 300 /** Windows/NT: Search the DLL load directory for imported DLLs - W7,
 301  *  Vista, and W2K8 requires KB2533623 to be installed to support this; not
 302  *  supported on XP, W2K3 or earlier.  Ignored on other platforms. */
 303 #define RTLDRLOAD_FLAGS_NT_SEARCH_DLL_LOAD_DIR  RT_BIT_32(2)
 304 /** Do not append default suffix.   */
 305 #define RTLDRLOAD_FLAGS_NO_SUFFIX               RT_BIT_32(3)
 306 /** Shift for the first .so.MAJOR version number to try.
 307  * Only applicable to RTLdrLoadSystemEx() and RTLdrGetSystemSymbolEx(). */
 308 #define RTLDRLOAD_FLAGS_SO_VER_BEGIN_SHIFT      12
 309 /** Mask for the first .so.MAJOR version number to try.
 310  * Only applicable to RTLdrLoadSystemEx() and RTLdrGetSystemSymbolEx(). */
 311 #define RTLDRLOAD_FLAGS_SO_VER_BEGIN_MASK       UINT32_C(0x003ff000)
 312 /** Shift for the end .so.MAJOR version number (exclusive).
 313  * Only applicable to RTLdrLoadSystemEx() and RTLdrGetSystemSymbolEx(). */
 314 #define RTLDRLOAD_FLAGS_SO_VER_END_SHIFT        22
 315 /** Mask for the end .so.MAJOR version number (exclusive).
 316  * Only applicable to RTLdrLoadSystemEx() and RTLdrGetSystemSymbolEx(). */
 317 #define RTLDRLOAD_FLAGS_SO_VER_END_MASK         UINT32_C(0xffc00000)
 318 /** Specifies the range for the .so.MAJOR version number.
 319  * Only applicable to RTLdrLoadSystemEx() and RTLdrGetSystemSymbolEx().
 320  * Ignored on systems not using .so.
 321  * @param a_uBegin  The first version to try.
 322  * @param a_uEnd    The version number to stop at (exclusive).
 323  */
 324 #define RTLDRLOAD_FLAGS_SO_VER_RANGE(a_uBegin, a_uEnd) \
 325     ( ((a_uBegin) << RTLDRLOAD_FLAGS_SO_VER_BEGIN_SHIFT) | ((a_uEnd) << RTLDRLOAD_FLAGS_SO_VER_END_SHIFT) )
 326 /** The mask of valid flag bits.
 327  * The shared object major version range is excluded. */
 328 #define RTLDRLOAD_FLAGS_VALID_MASK              UINT32_C(0x0000000f)
 329 /** @} */
 330
 331 /**
 332  * Loads a dynamic load library (/shared object) image file residing in one of
 333  * the default system library locations.
 334  *
 335  * Only the system library locations are searched. No suffix is required.
 336  *
 337  * @returns iprt status code.
 338  * @param   pszFilename Image filename. No path.
 339  * @param   fNoUnload   Do not unload the library when RTLdrClose is called.
 340  * @param   phLdrMod    Where to store the handle to the loaded module.
 341  */
 342 RTDECL(int) RTLdrLoadSystem(const char *pszFilename, bool fNoUnload, PRTLDRMOD phLdrMod);
 343
 344 /**
 345  * Loads a dynamic load library (/shared object) image file residing in one of
 346  * the default system library locations, extended version.
 347  *
 348  * Only the system library locations are searched. No suffix is required.
 349  *
 350  * @returns iprt status code.
 351  * @param   pszFilename Image filename. No path.
 352  * @param   fFlags      RTLDRLOAD_FLAGS_XXX, including RTLDRLOAD_FLAGS_SO_VER_XXX.
 353  * @param   phLdrMod    Where to store the handle to the loaded module.
 354  */
 355 RTDECL(int) RTLdrLoadSystemEx(const char *pszFilename, uint32_t fFlags, PRTLDRMOD phLdrMod);
 356
 357 /**
 358  * Combines RTLdrLoadSystem and RTLdrGetSymbol, with fNoUnload set to true.
 359  *
 360  * @returns The symbol value, NULL on failure.  (If you care for a less boolean
 361  *          status, go thru the necessary API calls yourself.)
 362  * @param   pszFilename Image filename. No path.
 363  * @param   pszSymbol   Symbol name.
 364  */
 365 RTDECL(void *) RTLdrGetSystemSymbol(const char *pszFilename, const char *pszSymbol);
 366
 367 /**
 368  * Combines RTLdrLoadSystemEx and RTLdrGetSymbol.
 369  *
 370  * @returns The symbol value, NULL on failure.  (If you care for a less boolean
 371  *          status, go thru the necessary API calls yourself.)
 372  * @param   pszFilename Image filename. No path.
 373  * @param   pszSymbol   Symbol name.
 374  * @param   fFlags      RTLDRLOAD_FLAGS_XXX, including RTLDRLOAD_FLAGS_SO_VER_XXX.
 375  */
 376 RTDECL(void *) RTLdrGetSystemSymbolEx(const char *pszFilename, const char *pszSymbol, uint32_t fFlags);
 377
 378 /**
 379  * Loads a dynamic load library (/shared object) image file residing in the
 380  * RTPathAppPrivateArch() directory.
 381  *
 382  * Suffix is not required.
 383  *
 384  * @returns iprt status code.
 385  * @param   pszFilename Image filename. No path.
 386  * @param   phLdrMod    Where to store the handle to the loaded module.
 387  */
 388 RTDECL(int) RTLdrLoadAppPriv(const char *pszFilename, PRTLDRMOD phLdrMod);
 389
 390 /**
 391  * Gets the native module handle for a module loaded by RTLdrLoad, RTLdrLoadEx,
 392  * RTLdrLoadSystem,  or RTLdrLoadAppPriv.
 393  *
 394  * @returns Native handle on success, ~(uintptr_t)0 on failure.
 395  * @param   hLdrMod     The loader module handle.
 396  */
 397 RTDECL(uintptr_t) RTLdrGetNativeHandle(RTLDRMOD hLdrMod);
 398
 399
 400 /**
 401  * Image architecuture specifier for RTLdrOpenEx.
 402  */
 403 typedef enum RTLDRARCH
 404 {
 405     RTLDRARCH_INVALID = 0,
 406     /** Whatever. */
 407     RTLDRARCH_WHATEVER,
 408     /** The host architecture. */
 409     RTLDRARCH_HOST,
 410     /** 16-bit x86. */
 411     RTLDRARCH_X86_16,
 412     /** 32-bit x86. */
 413     RTLDRARCH_X86_32,
 414     /** AMD64 (64-bit x86 if you like). */
 415     RTLDRARCH_AMD64,
 416     /** 32-bit ARM. */
 417     RTLDRARCH_ARM32,
 418     /** 64-bit ARM. */
 419     RTLDRARCH_ARM64,
 420     /** End of the valid values. */
 421     RTLDRARCH_END,
 422     /** Make sure the type is a full 32-bit. */
 423     RTLDRARCH_32BIT_HACK = 0x7fffffff
 424 } RTLDRARCH;
 425 /** Pointer to a RTLDRARCH. */
 426 typedef RTLDRARCH *PRTLDRARCH;
 427
 428 /**
 429  * Translates a RTLDRARCH value to a string.
 430  *
 431  * @returns Name corresponding to @a enmArch
 432  * @param   enmArch             The value to name.
 433  */
 434 RTDECL(const char *) RTLdrArchName(RTLDRARCH enmArch);
 435
 436 /**
 437  * Returns the host architecture.
 438  *
 439  * @returns Host architecture or RTLDRARCH_WHATEVER if no match.
 440  */
 441 RTDECL(RTLDRARCH) RTLdrGetHostArch(void);
 442
 443
 444 /** @name RTLDR_O_XXX - RTLdrOpen flags.
 445  * @{ */
 446 /** Open for debugging or introspection reasons.
 447  * This will skip a few of the stricter validations when loading images. */
 448 #define RTLDR_O_FOR_DEBUG                   RT_BIT_32(0)
 449 /** Open for signature validation. */
 450 #define RTLDR_O_FOR_VALIDATION              RT_BIT_32(1)
 451 /** The arch specification is just a guideline for FAT binaries. */
 452 #define RTLDR_O_WHATEVER_ARCH               RT_BIT_32(2)
 453 /** Ignore the architecture specification if there is no code. */
 454 #define RTLDR_O_IGNORE_ARCH_IF_NO_CODE      RT_BIT_32(3)
 455 /** Mach-O: Include the __LINKEDIT segment (ignored by the others). */
 456 #define RTLDR_O_MACHO_LOAD_LINKEDIT         RT_BIT_32(4)
 457 /** Mask of valid flags. */
 458 #define RTLDR_O_VALID_MASK                  UINT32_C(0x0000001f)
 459 /** @} */
 460
 461 /**
 462  * Open a binary image file.
 463  *
 464  * @returns iprt status code.
 465  * @param   pszFilename Image filename.
 466  * @param   fFlags      Valid RTLDR_O_XXX combination.
 467  * @param   enmArch     CPU architecture specifier for the image to be loaded.
 468  * @param   phLdrMod    Where to store the handle to the loader module.
 469  */
 470 RTDECL(int) RTLdrOpen(const char *pszFilename, uint32_t fFlags, RTLDRARCH enmArch, PRTLDRMOD phLdrMod);
 471
 472 /**
 473  * Open a binary image file, extended version.
 474  *
 475  * @returns iprt status code.
 476  * @param   pszFilename Image filename.
 477  * @param   fFlags      Valid RTLDR_O_XXX combination.
 478  * @param   enmArch     CPU architecture specifier for the image to be loaded.
 479  * @param   phLdrMod    Where to store the handle to the loader module.
 480  * @param   pErrInfo    Where to return extended error information. Optional.
 481  */
 482 RTDECL(int) RTLdrOpenEx(const char *pszFilename, uint32_t fFlags, RTLDRARCH enmArch, PRTLDRMOD phLdrMod, PRTERRINFO pErrInfo);
 483
 484 /**
 485  * Open a binary image file allowing VFS chains in the filename.
 486  *
 487  * @returns iprt status code.
 488  * @param   pszFilename Image filename, VFS chain specifiers allowed.
 489  * @param   fFlags      Valid RTLDR_O_XXX combination.
 490  * @param   enmArch     CPU architecture specifier for the image to be loaded.
 491  * @param   phLdrMod    Where to store the handle to the loader module.
 492  * @param   poffError   Where to return the offset into @a pszFilename of an VFS
 493  *                      chain element causing trouble.  Optional.
 494  * @param   pErrInfo    Where to return extended error information.  Optional.
 495  */
 496 RTDECL(int) RTLdrOpenVfsChain(const char *pszFilename, uint32_t fFlags, RTLDRARCH enmArch,
 497                               PRTLDRMOD phLdrMod, uint32_t *poffError, PRTERRINFO pErrInfo);
 498
 499 /**
 500  * Open part with reader.
 501  *
 502  * @returns iprt status code.
 503  * @param   pReader     The loader reader instance which will provide the raw
 504  *                      image bits.  The reader instance will be consumed on
 505  *                      success.  On failure, the caller has to do the cleaning
 506  *                      up.
 507  * @param   fFlags      Valid RTLDR_O_XXX combination.
 508  * @param   enmArch     Architecture specifier.
 509  * @param   phMod       Where to store the handle.
 510  * @param   pErrInfo    Where to return extended error information. Optional.
 511  */
 512 RTDECL(int) RTLdrOpenWithReader(PRTLDRREADER pReader, uint32_t fFlags, RTLDRARCH enmArch, PRTLDRMOD phMod, PRTERRINFO pErrInfo);
 513
 514 /**
 515  * Called to read @a cb bytes at @a off into @a pvBuf.
 516  *
 517  * @returns IPRT status code
 518  * @param   pvBuf       The output buffer.
 519  * @param   cb          The number of bytes to read.
 520  * @param   off         Where to start reading.
 521  * @param   pvUser      The user parameter.
 522  */
 523 typedef DECLCALLBACKTYPE(int, FNRTLDRRDRMEMREAD,(void *pvBuf, size_t cb, size_t off, void *pvUser));
 524 /** Pointer to a RTLdrOpenInMemory reader callback. */
 525 typedef FNRTLDRRDRMEMREAD *PFNRTLDRRDRMEMREAD;
 526
 527 /**
 528  * Called to when the module is unloaded (or done loading) to release resources
 529  * associated with it (@a pvUser).
 530  *
 531  * @param   pvUser      The user parameter.
 532  * @param   cbImage     The image size.
 533  */
 534 typedef DECLCALLBACKTYPE(void, FNRTLDRRDRMEMDTOR,(void *pvUser, size_t cbImage));
 535 /** Pointer to a RTLdrOpenInMemory destructor callback. */
 536 typedef FNRTLDRRDRMEMDTOR *PFNRTLDRRDRMEMDTOR;
 537
 538 /**
 539  * Open a in-memory image or an image with a custom reader callback.
 540  *
 541  * @returns IPRT status code.
 542  * @param   pszName     The image name.
 543  * @param   fFlags      Valid RTLDR_O_XXX combination.
 544  * @param   enmArch     CPU architecture specifier for the image to be loaded.
 545  * @param   cbImage     The size of the image (fake file).
 546  * @param   pfnRead     The read function.  If NULL is passed in, a default
 547  *                      reader function is provided that assumes @a pvUser
 548  *                      points to the raw image bits, at least @a cbImage of
 549  *                      valid memory.
 550  * @param   pfnDtor     The destructor function.  If NULL is passed, a default
 551  *                      destructor will be provided that passes @a pvUser to
 552  *                      RTMemFree.
 553  * @param   pvUser      The user argument or, if any of the callbacks are NULL,
 554  *                      a pointer to a memory block.
 555  * @param   phLdrMod    Where to return the module handle.
 556  * @param   pErrInfo    Pointer to an error info buffer, optional.
 557  *
 558  * @remarks With the exception of invalid @a pfnDtor and/or @a pvUser
 559  *          parameters, the pfnDtor methods (or the default one if NULL) will
 560  *          always be invoked.  The destruction of pvUser is entirely in the
 561  *          hands of this method once it's called.
 562  */
 563 RTDECL(int) RTLdrOpenInMemory(const char *pszName, uint32_t fFlags, RTLDRARCH enmArch, size_t cbImage,
 564                               PFNRTLDRRDRMEMREAD pfnRead, PFNRTLDRRDRMEMDTOR pfnDtor, void *pvUser,
 565                               PRTLDRMOD phLdrMod, PRTERRINFO pErrInfo);
 566
 567 /**
 568  * Closes a loader module handle.
 569  *
 570  * The handle can be obtained using any of the RTLdrLoad(), RTLdrOpen()
 571  * and RTLdrOpenInMemory() functions.
 572  *
 573  * @returns iprt status code.
 574  * @param   hLdrMod         The loader module handle.
 575  */
 576 RTDECL(int) RTLdrClose(RTLDRMOD hLdrMod);
 577
 578 /**
 579  * Gets the address of a named exported symbol.
 580  *
 581  * @returns iprt status code.
 582  * @retval  VERR_LDR_FORWARDER forwarder, use pfnQueryForwarderInfo. Buffer size
 583  *          hint in @a ppvValue.
 584  * @param   hLdrMod         The loader module handle.
 585  * @param   pszSymbol       Symbol name.
 586  * @param   ppvValue        Where to store the symbol value. Note that this is restricted to the
 587  *                          pointer size used on the host!
 588  */
 589 RTDECL(int) RTLdrGetSymbol(RTLDRMOD hLdrMod, const char *pszSymbol, void **ppvValue);
 590
 591 /**
 592  * Gets the address of a named exported symbol.
 593  *
 594  * This function differs from the plain one in that it can deal with
 595  * both GC and HC address sizes, and that it can calculate the symbol
 596  * value relative to any given base address.
 597  *
 598  * @returns iprt status code.
 599  * @retval  VERR_LDR_FORWARDER forwarder, use pfnQueryForwarderInfo. Buffer size
 600  *          hint in @a pValue.
 601  * @param   hLdrMod         The loader module handle.
 602  * @param   pvBits          Optional pointer to the loaded image.
 603  *                          Set this to NULL if no RTLdrGetBits() processed image bits are available.
 604  *                          Not supported for RTLdrLoad() images.
 605  * @param   BaseAddress     Image load address.
 606  *                          Not supported for RTLdrLoad() images.
 607  * @param   iOrdinal        Symbol ordinal number, pass UINT32_MAX if pszSymbol
 608  *                          should be used instead.
 609  * @param   pszSymbol       Symbol name.
 610  * @param   pValue          Where to store the symbol value.
 611  */
 612 RTDECL(int) RTLdrGetSymbolEx(RTLDRMOD hLdrMod, const void *pvBits, RTLDRADDR BaseAddress,
 613                              uint32_t iOrdinal, const char *pszSymbol, PRTLDRADDR pValue);
 614
 615 /**
 616  * Gets the address of a named exported function.
 617  *
 618  * Same as RTLdrGetSymbol, but skips the status code and pointer to return
 619  * variable stuff.
 620  *
 621  * @returns Pointer to the function if found, NULL if not.
 622  * @param   hLdrMod         The loader module handle.
 623  * @param   pszSymbol       Function name.
 624  */
 625 RTDECL(PFNRT) RTLdrGetFunction(RTLDRMOD hLdrMod, const char *pszSymbol);
 626
 627 /**
 628  * Information about an imported symbol.
 629  */
 630 typedef struct RTLDRIMPORTINFO
 631 {
 632     /** Symbol table entry number, UINT32_MAX if not available. */
 633     uint32_t        iSelfOrdinal;
 634     /** The ordinal of the imported symbol in szModule, UINT32_MAX if not used. */
 635     uint32_t        iOrdinal;
 636     /** The symbol name, NULL if not used.  This points to the char immediately
 637      *  following szModule when returned by RTLdrQueryForwarderInfo. */
 638     const char     *pszSymbol;
 639     /** The name of the module being imported from. */
 640     char            szModule[1];
 641 } RTLDRIMPORTINFO;
 642 /** Pointer to information about an imported symbol. */
 643 typedef RTLDRIMPORTINFO *PRTLDRIMPORTINFO;
 644 /** Pointer to const information about an imported symbol. */
 645 typedef RTLDRIMPORTINFO const *PCRTLDRIMPORTINFO;
 646
 647 /**
 648  * Query information about a forwarded symbol.
 649  *
 650  * @returns IPRT status code.
 651  * @param   hLdrMod         The loader module handle.
 652  * @param   pvBits          Optional pointer to the loaded image.
 653  *                          Set this to NULL if no RTLdrGetBits() processed image bits are available.
 654  *                          Not supported for RTLdrLoad() images.
 655  * @param   iOrdinal        Symbol ordinal number, pass UINT32_MAX if pszSymbol
 656  *                          should be used instead.
 657  * @param   pszSymbol       Symbol name.
 658  * @param   pInfo           Where to return the forwarder info.
 659  * @param   cbInfo          Size of the buffer @a pInfo points to.  For a size
 660  *                          hint, see @a pValue when RTLdrGetSymbolEx returns
 661  *                          VERR_LDR_FORWARDER.
 662  */
 663 RTDECL(int) RTLdrQueryForwarderInfo(RTLDRMOD hLdrMod, const void *pvBits, uint32_t iOrdinal, const char *pszSymbol,
 664                                     PRTLDRIMPORTINFO pInfo, size_t cbInfo);
 665
 666
 667 /**
 668  * Gets the size of the loaded image.
 669  *
 670  * This is not necessarily available for images that has been loaded using
 671  * RTLdrLoad().
 672  *
 673  * @returns image size (in bytes).
 674  * @returns ~(size_t)0 on if not available.
 675  * @param   hLdrMod     Handle to the loader module.
 676  */
 677 RTDECL(size_t) RTLdrSize(RTLDRMOD hLdrMod);
 678
 679 /**
 680  * Resolve an external symbol during RTLdrGetBits().
 681  *
 682  * @returns iprt status code.
 683  * @param   hLdrMod         The loader module handle.
 684  * @param   pszModule       Module name.
 685  * @param   pszSymbol       Symbol name, NULL if uSymbol should be used.
 686  * @param   uSymbol         Symbol ordinal, ~0 if pszSymbol should be used.
 687  * @param   pValue          Where to store the symbol value (address).
 688  * @param   pvUser          User argument.
 689  */
 690 typedef DECLCALLBACKTYPE(int, FNRTLDRIMPORT,(RTLDRMOD hLdrMod, const char *pszModule, const char *pszSymbol, unsigned uSymbol,
 691                                              PRTLDRADDR pValue, void *pvUser));
 692 /** Pointer to a FNRTLDRIMPORT() callback function. */
 693 typedef FNRTLDRIMPORT *PFNRTLDRIMPORT;
 694
 695 /**
 696  * Loads the image into a buffer provided by the user and applies fixups
 697  * for the given base address.
 698  *
 699  * @returns iprt status code.
 700  * @param   hLdrMod         The load module handle.
 701  * @param   pvBits          Where to put the bits.
 702  *                          Must be as large as RTLdrSize() suggests.
 703  * @param   BaseAddress     The base address.
 704  * @param   pfnGetImport    Callback function for resolving imports one by one.
 705  * @param   pvUser          User argument for the callback.
 706  * @remark  Not supported for RTLdrLoad() images.
 707  */
 708 RTDECL(int) RTLdrGetBits(RTLDRMOD hLdrMod, void *pvBits, RTLDRADDR BaseAddress, PFNRTLDRIMPORT pfnGetImport, void *pvUser);
 709
 710 /**
 711  * Relocates bits after getting them.
 712  * Useful for code which moves around a bit.
 713  *
 714  * @returns iprt status code.
 715  * @param   hLdrMod             The loader module handle.
 716  * @param   pvBits              Where the image bits are.
 717  *                              Must have been passed to RTLdrGetBits().
 718  * @param   NewBaseAddress      The new base address.
 719  * @param   OldBaseAddress      The old base address.
 720  * @param   pfnGetImport        Callback function for resolving imports one by one.
 721  * @param   pvUser              User argument for the callback.
 722  * @remark  Not supported for RTLdrLoad() images.
 723  */
 724 RTDECL(int) RTLdrRelocate(RTLDRMOD hLdrMod, void *pvBits, RTLDRADDR NewBaseAddress, RTLDRADDR OldBaseAddress,
 725                           PFNRTLDRIMPORT pfnGetImport, void *pvUser);
 726
 727 /**
 728  * Enumeration callback function used by RTLdrEnumSymbols().
 729  *
 730  * @returns iprt status code. Failure will stop the enumeration.
 731  * @param   hLdrMod         The loader module handle.
 732  * @param   pszSymbol       Symbol name. NULL if ordinal only.
 733  * @param   uSymbol         Symbol ordinal, ~0 if not used.
 734  * @param   Value           Symbol value.
 735  * @param   pvUser          The user argument specified to RTLdrEnumSymbols().
 736  */
 737 typedef DECLCALLBACKTYPE(int, FNRTLDRENUMSYMS,(RTLDRMOD hLdrMod, const char *pszSymbol, unsigned uSymbol, RTLDRADDR Value, void *pvUser));
 738 /** Pointer to a FNRTLDRENUMSYMS() callback function. */
 739 typedef FNRTLDRENUMSYMS *PFNRTLDRENUMSYMS;
 740
 741 /**
 742  * Enumerates all symbols in a module.
 743  *
 744  * @returns iprt status code.
 745  * @param   hLdrMod         The loader module handle.
 746  * @param   fFlags          Flags indicating what to return and such.
 747  * @param   pvBits          Optional pointer to the loaded image. (RTLDR_ENUM_SYMBOL_FLAGS_*)
 748  *                          Set this to NULL if no RTLdrGetBits() processed image bits are available.
 749  * @param   BaseAddress     Image load address.
 750  * @param   pfnCallback     Callback function.
 751  * @param   pvUser          User argument for the callback.
 752  * @remark  Not supported for RTLdrLoad() images.
 753  */
 754 RTDECL(int) RTLdrEnumSymbols(RTLDRMOD hLdrMod, unsigned fFlags, const void *pvBits, RTLDRADDR BaseAddress, PFNRTLDRENUMSYMS pfnCallback, void *pvUser);
 755
 756 /** @name RTLdrEnumSymbols flags.
 757  * @{ */
 758 /** Returns ALL kinds of symbols. The default is to only return public/exported symbols. */
 759 #define RTLDR_ENUM_SYMBOL_FLAGS_ALL             RT_BIT(1)
 760 /** Ignore forwarders rather than reporting them with RTLDR_ENUM_SYMBOL_FWD_ADDRESS as value. */
 761 #define RTLDR_ENUM_SYMBOL_FLAGS_NO_FWD          RT_BIT(2)
 762 /** @} */
 763
 764 /** Special symbol for forwarder symbols, since they cannot be resolved with
 765  * the current API. */
 766 #if (HC_ARCH_BITS == 64 || GC_ARCH_BITS == 64)
 767 # define RTLDR_ENUM_SYMBOL_FWD_ADDRESS          UINT64_C(0xff4242fffd4242fd)
 768 #else
 769 # define RTLDR_ENUM_SYMBOL_FWD_ADDRESS          UINT32_C(0xff4242fd)
 770 #endif
 771
 772
 773 /**
 774  * Debug info type (as far the loader can tell).
 775  */
 776 typedef enum RTLDRDBGINFOTYPE
 777 {
 778     /** The invalid 0 value. */
 779     RTLDRDBGINFOTYPE_INVALID = 0,
 780     /** Unknown debug info format. */
 781     RTLDRDBGINFOTYPE_UNKNOWN,
 782     /** Stabs. */
 783     RTLDRDBGINFOTYPE_STABS,
 784     /** Debug With Arbitrary Record Format (DWARF). */
 785     RTLDRDBGINFOTYPE_DWARF,
 786     /** Debug With Arbitrary Record Format (DWARF), in external file (DWO). */
 787     RTLDRDBGINFOTYPE_DWARF_DWO,
 788     /** Microsoft Codeview debug info. */
 789     RTLDRDBGINFOTYPE_CODEVIEW,
 790     /** Microsoft Codeview debug info, in external v2.0+ program database (PDB). */
 791     RTLDRDBGINFOTYPE_CODEVIEW_PDB20,
 792     /** Microsoft Codeview debug info, in external v7.0+ program database (PDB). */
 793     RTLDRDBGINFOTYPE_CODEVIEW_PDB70,
 794     /** Microsoft Codeview debug info, in external file (DBG). */
 795     RTLDRDBGINFOTYPE_CODEVIEW_DBG,
 796     /** Microsoft COFF debug info. */
 797     RTLDRDBGINFOTYPE_COFF,
 798     /** Watcom debug info. */
 799     RTLDRDBGINFOTYPE_WATCOM,
 800     /** IBM High Level Language debug info. */
 801     RTLDRDBGINFOTYPE_HLL,
 802     /** The end of the valid debug info values (exclusive). */
 803     RTLDRDBGINFOTYPE_END,
 804     /** Blow the type up to 32-bits. */
 805     RTLDRDBGINFOTYPE_32BIT_HACK = 0x7fffffff
 806 } RTLDRDBGINFOTYPE;
 807
 808
 809 /**
 810  * Debug info details for the enumeration callback.
 811  */
 812 typedef struct RTLDRDBGINFO
 813 {
 814     /** The kind of debug info. */
 815     RTLDRDBGINFOTYPE    enmType;
 816     /** The debug info ordinal number / id. */
 817     uint32_t            iDbgInfo;
 818     /** The file offset *if* this type has one specific location in the executable
 819      * image file. This is -1 if there isn't any specific file location. */
 820     RTFOFF              offFile;
 821     /** The link address of the debug info if it's loadable. NIL_RTLDRADDR if not
 822      * loadable*/
 823     RTLDRADDR           LinkAddress;
 824     /** The size of the debug information. -1 is used if this isn't applicable.*/
 825     RTLDRADDR           cb;
 826     /** This is set if the debug information is found in an external file.  NULL
 827      * if no external file involved.
 828      * @note Putting it outside the union to allow lazy callback implementation. */
 829     const char         *pszExtFile;
 830     /** Type (enmType) specific information. */
 831     union
 832     {
 833         /** RTLDRDBGINFOTYPE_DWARF */
 834         struct
 835         {
 836             /** The section name. */
 837             const char *pszSection;
 838         } Dwarf;
 839
 840         /** RTLDRDBGINFOTYPE_DWARF_DWO */
 841         struct
 842         {
 843             /** The CRC32 of the external file. */
 844             uint32_t    uCrc32;
 845         } Dwo;
 846
 847         /** RTLDRDBGINFOTYPE_CODEVIEW, RTLDRDBGINFOTYPE_COFF  */
 848         struct
 849         {
 850             /** The PE image size. */
 851             uint32_t    cbImage;
 852             /** The timestamp. */
 853             uint32_t    uTimestamp;
 854             /** The major version from the entry. */
 855             uint32_t    uMajorVer;
 856             /** The minor version from the entry. */
 857             uint32_t    uMinorVer;
 858         } Cv, Coff;
 859
 860         /** RTLDRDBGINFOTYPE_CODEVIEW_DBG */
 861         struct
 862         {
 863             /** The PE image size. */
 864             uint32_t    cbImage;
 865             /** The timestamp. */
 866             uint32_t    uTimestamp;
 867         } Dbg;
 868
 869         /** RTLDRDBGINFOTYPE_CODEVIEW_PDB20*/
 870         struct
 871         {
 872             /** The PE image size. */
 873             uint32_t    cbImage;
 874             /** The timestamp. */
 875             uint32_t    uTimestamp;
 876             /** The PDB age. */
 877             uint32_t    uAge;
 878         } Pdb20;
 879
 880         /** RTLDRDBGINFOTYPE_CODEVIEW_PDB70 */
 881         struct
 882         {
 883             /** The PE image size. */
 884             uint32_t    cbImage;
 885             /** The PDB age. */
 886             uint32_t    uAge;
 887             /** The UUID. */
 888             RTUUID      Uuid;
 889         } Pdb70;
 890     } u;
 891 } RTLDRDBGINFO;
 892 /** Pointer to debug info details. */
 893 typedef RTLDRDBGINFO *PRTLDRDBGINFO;
 894 /** Pointer to read only debug info details. */
 895 typedef RTLDRDBGINFO const *PCRTLDRDBGINFO;
 896
 897
 898 /**
 899  * Debug info enumerator callback.
 900  *
 901  * @returns VINF_SUCCESS to continue the enumeration.  Any other status code
 902  *          will cause RTLdrEnumDbgInfo to immediately return with that status.
 903  *
 904  * @param   hLdrMod         The module handle.
 905  * @param   pDbgInfo        Pointer to a read only structure with the details.
 906  * @param   pvUser          The user parameter specified to RTLdrEnumDbgInfo.
 907  */
 908 typedef DECLCALLBACKTYPE(int, FNRTLDRENUMDBG,(RTLDRMOD hLdrMod, PCRTLDRDBGINFO pDbgInfo, void *pvUser));
 909 /** Pointer to a debug info enumerator callback. */
 910 typedef FNRTLDRENUMDBG *PFNRTLDRENUMDBG;
 911
 912 /**
 913  * Enumerate the debug info contained in the executable image.
 914  *
 915  * @returns IPRT status code or whatever pfnCallback returns.
 916  *
 917  * @param   hLdrMod         The module handle.
 918  * @param   pvBits          Optional pointer to bits returned by
 919  *                          RTLdrGetBits().  This can be used by some module
 920  *                          interpreters to reduce memory consumption.
 921  * @param   pfnCallback     The callback function.
 922  * @param   pvUser          The user argument.
 923  */
 924 RTDECL(int) RTLdrEnumDbgInfo(RTLDRMOD hLdrMod, const void *pvBits, PFNRTLDRENUMDBG pfnCallback, void *pvUser);
 925
 926
 927 /**
 928  * Loader segment.
 929  */
 930 typedef struct RTLDRSEG
 931 {
 932     /** The segment name.  Always set to something. */
 933     const char     *pszName;
 934     /** The length of the segment name. */
 935     uint32_t        cchName;
 936     /** The flat selector to use for the segment (i.e. data/code).
 937      * Primarily a way for the user to specify selectors for the LX/LE and NE interpreters. */
 938     uint16_t        SelFlat;
 939     /** The 16-bit selector to use for the segment.
 940      * Primarily a way for the user to specify selectors for the LX/LE and NE interpreters. */
 941     uint16_t        Sel16bit;
 942     /** Segment flags. */
 943     uint32_t        fFlags;
 944     /** The segment protection (RTMEM_PROT_XXX). */
 945     uint32_t        fProt;
 946     /** The size of the segment. */
 947     RTLDRADDR       cb;
 948     /** The required segment alignment.
 949      * The to 0 if the segment isn't supposed to be mapped. */
 950     RTLDRADDR       Alignment;
 951     /** The link address.
 952      * Set to NIL_RTLDRADDR if the segment isn't supposed to be mapped or if
 953      * the image doesn't have link addresses. */
 954     RTLDRADDR       LinkAddress;
 955     /** File offset of the segment.
 956      * Set to -1 if no file backing (like BSS). */
 957     RTFOFF          offFile;
 958     /** Size of the file bits of the segment.
 959      * Set to -1 if no file backing (like BSS). */
 960     RTFOFF          cbFile;
 961     /** The relative virtual address when mapped.
 962      * Set to NIL_RTLDRADDR if the segment isn't supposed to be mapped. */
 963     RTLDRADDR       RVA;
 964     /** The size of the segment including the alignment gap up to the next segment when mapped.
 965      * This is set to NIL_RTLDRADDR if not implemented. */
 966     RTLDRADDR       cbMapped;
 967 } RTLDRSEG;
 968 /** Pointer to a loader segment. */
 969 typedef RTLDRSEG *PRTLDRSEG;
 970 /** Pointer to a read only loader segment. */
 971 typedef RTLDRSEG const *PCRTLDRSEG;
 972
 973
 974 /** @name Segment flags
 975  * @{ */
 976 /** The segment is 16-bit. When not set the default of the target architecture is assumed. */
 977 #define RTLDRSEG_FLAG_16BIT         UINT32_C(1)
 978 /** The segment requires a 16-bit selector alias. (OS/2) */
 979 #define RTLDRSEG_FLAG_OS2_ALIAS16   UINT32_C(2)
 980 /** Conforming segment (x86 weirdness). (OS/2) */
 981 #define RTLDRSEG_FLAG_OS2_CONFORM   UINT32_C(4)
 982 /** IOPL (ring-2) segment. (OS/2) */
 983 #define RTLDRSEG_FLAG_OS2_IOPL      UINT32_C(8)
 984 /** @} */
 985
 986 /**
 987  * Segment enumerator callback.
 988  *
 989  * @returns VINF_SUCCESS to continue the enumeration.  Any other status code
 990  *          will cause RTLdrEnumSegments to immediately return with that
 991  *          status.
 992  *
 993  * @param   hLdrMod         The module handle.
 994  * @param   pSeg            The segment information.
 995  * @param   pvUser          The user parameter specified to RTLdrEnumSegments.
 996  */
 997 typedef DECLCALLBACKTYPE(int, FNRTLDRENUMSEGS,(RTLDRMOD hLdrMod, PCRTLDRSEG pSeg, void *pvUser));
 998 /** Pointer to a segment enumerator callback. */
 999 typedef FNRTLDRENUMSEGS *PFNRTLDRENUMSEGS;
1000
1001 /**
1002  * Enumerate the debug info contained in the executable image.
1003  *
1004  * @returns IPRT status code or whatever pfnCallback returns.
1005  *
1006  * @param   hLdrMod         The module handle.
1007  * @param   pfnCallback     The callback function.
1008  * @param   pvUser          The user argument.
1009  */
1010 RTDECL(int) RTLdrEnumSegments(RTLDRMOD hLdrMod, PFNRTLDRENUMSEGS pfnCallback, void *pvUser);
1011
1012 /**
1013  * LX specific API for setting the selectors of a segment before getting
1014  * segment bits.
1015  *
1016  * @returns IPRT status code.
1017  * @param   hLdrMod         The module handle.
1018  * @param   iSegment        The segment to set the selectors for.
1019  * @param   Sel16bit        The 16-bit selector.
1020  * @param   SelFlat         The flat selector.
1021  */
1022 RTDECL(int) RTLdrLxSetSegmentSelectors(RTLDRMOD hLdrMod, uint32_t iSegment, uint16_t Sel16bit, uint16_t SelFlat);
1023
1024 /**
1025  * Converts a link address to a segment:offset address.
1026  *
1027  * @returns IPRT status code.
1028  *
1029  * @param   hLdrMod         The module handle.
1030  * @param   LinkAddress     The link address to convert.
1031  * @param   piSeg           Where to return the segment index.
1032  * @param   poffSeg         Where to return the segment offset.
1033  */
1034 RTDECL(int) RTLdrLinkAddressToSegOffset(RTLDRMOD hLdrMod, RTLDRADDR LinkAddress, uint32_t *piSeg, PRTLDRADDR poffSeg);
1035
1036 /**
1037  * Converts a link address to an image relative virtual address (RVA).
1038  *
1039  * @returns IPRT status code.
1040  *
1041  * @param   hLdrMod         The module handle.
1042  * @param   LinkAddress     The link address to convert.
1043  * @param   pRva            Where to return the RVA.
1044  */
1045 RTDECL(int) RTLdrLinkAddressToRva(RTLDRMOD hLdrMod, RTLDRADDR LinkAddress, PRTLDRADDR pRva);
1046
1047 /**
1048  * Converts an image relative virtual address (RVA) to a segment:offset.
1049  *
1050  * @returns IPRT status code.
1051  *
1052  * @param   hLdrMod         The module handle.
1053  * @param   iSeg            The segment index.
1054  * @param   offSeg          The segment offset.
1055  * @param   pRva            Where to return the RVA.
1056  */
1057 RTDECL(int) RTLdrSegOffsetToRva(RTLDRMOD hLdrMod, uint32_t iSeg, RTLDRADDR offSeg, PRTLDRADDR pRva);
1058
1059 /**
1060  * Converts a segment:offset into an image relative virtual address (RVA).
1061  *
1062  * @returns IPRT status code.
1063  *
1064  * @param   hLdrMod         The module handle.
1065  * @param   Rva             The link address to convert.
1066  * @param   piSeg           Where to return the segment index.
1067  * @param   poffSeg         Where to return the segment offset.
1068  */
1069 RTDECL(int) RTLdrRvaToSegOffset(RTLDRMOD hLdrMod, RTLDRADDR Rva, uint32_t *piSeg, PRTLDRADDR poffSeg);
1070
1071 /**
1072  * Gets the image format.
1073  *
1074  * @returns Valid image format on success. RTLDRFMT_INVALID on invalid handle or
1075  *          other errors.
1076  * @param   hLdrMod         The module handle.
1077  */
1078 RTDECL(RTLDRFMT) RTLdrGetFormat(RTLDRMOD hLdrMod);
1079
1080 /**
1081  * Gets the image type.
1082  *
1083  * @returns Valid image type value on success. RTLDRTYPE_INVALID on
1084  *          invalid handle or other errors.
1085  * @param   hLdrMod         The module handle.
1086  */
1087 RTDECL(RTLDRTYPE) RTLdrGetType(RTLDRMOD hLdrMod);
1088
1089 /**
1090  * Gets the image endian-ness.
1091  *
1092  * @returns Valid image endian value on success. RTLDRENDIAN_INVALID on invalid
1093  *          handle or other errors.
1094  * @param   hLdrMod         The module handle.
1095  */
1096 RTDECL(RTLDRENDIAN) RTLdrGetEndian(RTLDRMOD hLdrMod);
1097
1098 /**
1099  * Gets the image endian-ness.
1100  *
1101  * @returns Valid image architecture value on success.
1102  *          RTLDRARCH_INVALID on invalid handle or other errors.
1103  * @param   hLdrMod         The module handle.
1104  */
1105 RTDECL(RTLDRARCH) RTLdrGetArch(RTLDRMOD hLdrMod);
1106
1107 /**
1108  * Loader properties that can be queried thru RTLdrQueryProp.
1109  */
1110 typedef enum RTLDRPROP
1111 {
1112     RTLDRPROP_INVALID = 0,
1113     /** The image UUID (Mach-O).
1114      * Returns a RTUUID in the buffer. */
1115     RTLDRPROP_UUID,
1116     /** The image timestamp in seconds, genrally since unix epoc.
1117      * Returns a 32-bit or 64-bit signed integer value in the buffer. */
1118     RTLDRPROP_TIMESTAMP_SECONDS,
1119     /** Checks if the image is signed.
1120      * Returns a bool.  */
1121     RTLDRPROP_IS_SIGNED,
1122     /** Retrives the PKCS \#7 SignedData blob that signs the image.
1123      * Returns variable sized buffer containing the ASN.1 BER encoding.
1124      *
1125      * @remarks This generally starts with a PKCS \#7 Content structure, the
1126      *          SignedData bit is found a few levels down into this as per RFC. */
1127     RTLDRPROP_PKCS7_SIGNED_DATA,
1128     /** Query the number of pages that needs hashing.
1129      * This is for RTLDRPROP_SHA1_PAGE_HASHES and RTLDRPROP_SHA256_PAGE_HASHES
1130      * buffer size calculations. */
1131     RTLDRPROP_HASHABLE_PAGES,
1132     /** Query the SHA-1 page hashes.
1133      * Returns an array with entries made of a 32-bit file offset and a SHA-1
1134      * digest.  Use RTLDRPROP_HASHABLE_PAGES to calculate the buffer size. */
1135     RTLDRPROP_SHA1_PAGE_HASHES,
1136     /** Query the SHA-256 page hashes.
1137      * Returns an array with entries made of a 32-bit file offset and a SHA-256
1138      * digest. Use RTLDRPROP_HASHABLE_PAGES to calculate the buffer size. */
1139     RTLDRPROP_SHA256_PAGE_HASHES,
1140
1141     /** Query whether code signature checks are enabled.  */
1142     RTLDRPROP_SIGNATURE_CHECKS_ENFORCED,
1143
1144     /** Number of import or needed modules. */
1145     RTLDRPROP_IMPORT_COUNT,
1146     /** Import module by index (32-bit) stored in the buffer. */
1147     RTLDRPROP_IMPORT_MODULE,
1148     /** The file offset of the main executable header.
1149      * This is mainly for PE, NE and LX headers, but also Mach-O FAT. */
1150     RTLDRPROP_FILE_OFF_HEADER,
1151     /** The internal module name.
1152      * This is the SONAME for ELF, export table name for PE, and zero'th resident
1153      * name table entry for LX.
1154      * Returns zero terminated string. */
1155     RTLDRPROP_INTERNAL_NAME,
1156     /** The raw unwind table if available.
1157      * For PE this means IMAGE_DIRECTORY_ENTRY_EXCEPTION content, for AMD64 this
1158      * is the lookup table (IMAGE_RUNTIME_FUNCTION_ENTRY).
1159      * Not implemented any others yet.  */
1160     RTLDRPROP_UNWIND_TABLE,
1161     /** Read unwind info at given RVA and up to buffer size.  The RVA is stored
1162      * as uint32_t in the buffer when making the call.
1163      * This is only implemented for PE.  */
1164     RTLDRPROP_UNWIND_INFO,
1165     /** The image build-id (ELF/GNU).
1166      * Returns usually a SHA1 checksum in the buffer. */
1167     RTLDRPROP_BUILDID,
1168
1169     /** End of valid properties.  */
1170     RTLDRPROP_END,
1171     /** Blow the type up to 32 bits. */
1172     RTLDRPROP_32BIT_HACK = 0x7fffffff
1173 } RTLDRPROP;
1174
1175 /**
1176  * Generic method for querying image properties.
1177  *
1178  * @returns IPRT status code.
1179  * @retval  VERR_NOT_SUPPORTED if the property query isn't supported (either all
1180  *          or that specific property).  The caller must handle this result.
1181  * @retval  VERR_NOT_FOUND the property was not found in the module.  The caller
1182  *          must also normally deal with this.
1183  * @retval  VERR_INVALID_FUNCTION if the function value is wrong.
1184  * @retval  VERR_INVALID_PARAMETER if the buffer size is wrong.
1185  * @retval  VERR_BUFFER_OVERFLOW if the function doesn't have a fixed size
1186  *          buffer and the buffer isn't big enough.  Use RTLdrQueryPropEx.
1187  * @retval  VERR_INVALID_HANDLE if the handle is invalid.
1188  *
1189  * @param   hLdrMod         The module handle.
1190  * @param   enmProp         The property to query.
1191  * @param   pvBuf           Pointer to the input / output buffer.  In most cases
1192  *                          it's only used for returning data.
1193  * @param   cbBuf           The size of the buffer.
1194  */
1195 RTDECL(int) RTLdrQueryProp(RTLDRMOD hLdrMod, RTLDRPROP enmProp, void *pvBuf, size_t cbBuf);
1196
1197 /**
1198  * Generic method for querying image properties, extended version.
1199  *
1200  * @returns IPRT status code.
1201  * @retval  VERR_NOT_SUPPORTED if the property query isn't supported (either all
1202  *          or that specific property).  The caller must handle this result.
1203  * @retval  VERR_NOT_FOUND the property was not found in the module.  The caller
1204  *          must also normally deal with this.
1205  * @retval  VERR_INVALID_FUNCTION if the function value is wrong.
1206  * @retval  VERR_INVALID_PARAMETER if the fixed buffer size is wrong. Correct
1207  *          size in @a *pcbRet.
1208  * @retval  VERR_BUFFER_OVERFLOW if the function doesn't have a fixed size
1209  *          buffer and the buffer isn't big enough. Correct size in @a *pcbRet.
1210  * @retval  VERR_INVALID_HANDLE if the handle is invalid.
1211  *
1212  * @param   hLdrMod         The module handle.
1213  * @param   enmProp         The property to query.
1214  * @param   pvBits          Optional pointer to bits returned by
1215  *                          RTLdrGetBits().  This can be utilized by some module
1216  *                          interpreters to reduce memory consumption and file
1217  *                          access.
1218  * @param   pvBuf           Pointer to the input / output buffer.  In most cases
1219  *                          it's only used for returning data.
1220  * @param   cbBuf           The size of the buffer.
1221  * @param   pcbRet          Where to return the amount of data returned.  On
1222  *                          buffer size errors, this is set to the correct size.
1223  *                          Optional.
1224  */
1225 RTDECL(int) RTLdrQueryPropEx(RTLDRMOD hLdrMod, RTLDRPROP enmProp, void *pvBits, void *pvBuf, size_t cbBuf, size_t *pcbRet);
1226
1227
1228 /**
1229  * Signature type, see FNRTLDRVALIDATESIGNEDDATA.
1230  */
1231 typedef enum RTLDRSIGNATURETYPE
1232 {
1233     /** Invalid value. */
1234     RTLDRSIGNATURETYPE_INVALID = 0,
1235     /** A RTPKCS7CONTENTINFO structure w/ RTPKCS7SIGNEDDATA inside.
1236      * It's parsed, so the whole binary ASN.1 representation can be found by
1237      * using RTASN1CORE_GET_RAW_ASN1_PTR() and RTASN1CORE_GET_RAW_ASN1_SIZE(). */
1238     RTLDRSIGNATURETYPE_PKCS7_SIGNED_DATA,
1239     /** End of valid values. */
1240     RTLDRSIGNATURETYPE_END,
1241     /** Make sure the size is 32-bit. */
1242     RTLDRSIGNATURETYPE_32BIT_HACK = 0x7fffffff
1243 } RTLDRSIGNATURETYPE;
1244
1245 /**
1246  * Signature information provided by FNRTLDRVALIDATESIGNEDDATA.
1247  */
1248 typedef struct RTLDRSIGNATUREINFO
1249 {
1250     /** The signature number (0-based). */
1251     uint16_t            iSignature;
1252     /** The total number of signatures. */
1253     uint16_t            cSignatures;
1254     /** Sginature format type. */
1255     RTLDRSIGNATURETYPE  enmType;
1256     /** The signature data (formatted according to enmType). */
1257     void const         *pvSignature;
1258     /** The size of the buffer pvSignature points to. */
1259     size_t              cbSignature;
1260     /** Pointer to the signed data, if external.
1261      * NULL if the data is internal to the signature structure. */
1262     void const         *pvExternalData;
1263     /** Size of the signed data, if external.
1264      * 0 if internal to the signature structure. */
1265     size_t              cbExternalData;
1266 } RTLDRSIGNATUREINFO;
1267 /** Pointer to a signature structure. */
1268 typedef RTLDRSIGNATUREINFO *PRTLDRSIGNATUREINFO;
1269 /** Pointer to a const signature structure. */
1270 typedef RTLDRSIGNATUREINFO const *PCRTLDRSIGNATUREINFO;
1271
1272 /**
1273  * Callback used by RTLdrVerifySignature to verify the signature and associated
1274  * certificates.
1275  *
1276  * This is called multiple times when the executable contains more than one
1277  * signature (PE only at the moment).  The RTLDRSIGNATUREINFO::cSignatures gives
1278  * the total number of signatures (and thereby callbacks) and
1279  * RTLDRSIGNATUREINFO::iSignature indicates the current one.
1280  *
1281  * @returns IPRT status code.  A status code other than VINF_SUCCESS will
1282  *          prevent callbacks the remaining signatures (if any).
1283  * @param   hLdrMod         The module handle.
1284  * @param   pInfo           Signature information.
1285  * @param   pErrInfo        Pointer to an error info buffer, optional.
1286  * @param   pvUser          User argument.
1287  */
1288 typedef DECLCALLBACKTYPE(int, FNRTLDRVALIDATESIGNEDDATA,(RTLDRMOD hLdrMod, PCRTLDRSIGNATUREINFO pInfo,
1289                                                          PRTERRINFO pErrInfo, void *pvUser));
1290 /** Pointer to a signature verification callback. */
1291 typedef FNRTLDRVALIDATESIGNEDDATA *PFNRTLDRVALIDATESIGNEDDATA;
1292
1293 /**
1294  * Verify the image signature.
1295  *
1296  * This may permform additional integrity checks on the image structures that
1297  * was not done when opening the image.
1298  *
1299  * @returns IPRT status code.
1300  * @retval  VERR_LDRVI_NOT_SIGNED if not signed.
1301  *
1302  * @param   hLdrMod         The module handle.
1303  * @param   pfnCallback     Callback that does the signature and certificate
1304  *                          verficiation.
1305  * @param   pvUser          User argument for the callback.
1306  * @param   pErrInfo        Pointer to an error info buffer. Optional.
1307  */
1308 RTDECL(int) RTLdrVerifySignature(RTLDRMOD hLdrMod, PFNRTLDRVALIDATESIGNEDDATA pfnCallback, void *pvUser, PRTERRINFO pErrInfo);
1309
1310 /**
1311  * Calculate the image hash according the image signing rules.
1312  *
1313  * @returns IPRT status code.
1314  * @param   hLdrMod         The module handle.
1315  * @param   enmDigest       Which kind of digest.
1316  * @param   pabHash         Where to store the image hash.
1317  * @param   cbHash          Size of the buffer @a pabHash points at.  The
1318  *                          required and returned size can be derived from the
1319  *                          digest type (@a enmDigest).
1320  */
1321 RTDECL(int) RTLdrHashImage(RTLDRMOD hLdrMod, RTDIGESTTYPE enmDigest, uint8_t *pabHash, size_t cbHash);
1322
1323 /**
1324  * Try use unwind information to unwind one frame.
1325  *
1326  * @returns IPRT status code.  Last informational status from stack reader callback.
1327  * @retval  VERR_DBG_NO_UNWIND_INFO if the module contains no unwind information.
1328  * @retval  VERR_DBG_UNWIND_INFO_NOT_FOUND if no unwind information was found
1329  *          for the location given by iSeg:off.
1330  *
1331  * @param   hLdrMod         The module handle.
1332  * @param   pvBits          Optional pointer to bits returned by
1333  *                          RTLdrGetBits().  This can be utilized by some module
1334  *                          interpreters to reduce memory consumption and file
1335  *                          access.
1336  * @param   iSeg            The segment number of the program counter.  UINT32_MAX if RVA.
1337  * @param   off             The offset into @a iSeg.  Together with @a iSeg
1338  *                          this corresponds to the RTDBGUNWINDSTATE::uPc
1339  *                          value pointed to by @a pState.
1340  * @param   pState          The unwind state to work.
1341  *
1342  * @sa      RTDbgModUnwindFrame
1343  */
1344 RTDECL(int) RTLdrUnwindFrame(RTLDRMOD hLdrMod, void const *pvBits, uint32_t iSeg, RTLDRADDR off, PRTDBGUNWINDSTATE pState);
1345
1346 RT_C_DECLS_END
1347
1348 /** @} */
1349
1350 #endif /* !IPRT_INCLUDED_ldr_h */
1351