[1] | 1 | /** @file
|
---|
[8245] | 2 | * IPRT - Loader.
|
---|
[1] | 3 | */
|
---|
| 4 |
|
---|
| 5 | /*
|
---|
[98103] | 6 | * Copyright (C) 2006-2023 Oracle and/or its affiliates.
|
---|
[1] | 7 | *
|
---|
[96407] | 8 | * This file is part of VirtualBox base platform packages, as
|
---|
| 9 | * available from https://www.virtualbox.org.
|
---|
[5999] | 10 | *
|
---|
[96407] | 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 | *
|
---|
[5999] | 24 | * The contents of this file may alternatively be used under the terms
|
---|
| 25 | * of the Common Development and Distribution License Version 1.0
|
---|
[96407] | 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
|
---|
[5999] | 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.
|
---|
[96407] | 32 | *
|
---|
| 33 | * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
|
---|
[1] | 34 | */
|
---|
| 35 |
|
---|
[76557] | 36 | #ifndef IPRT_INCLUDED_ldr_h
|
---|
| 37 | #define IPRT_INCLUDED_ldr_h
|
---|
[76507] | 38 | #ifndef RT_WITHOUT_PRAGMA_ONCE
|
---|
| 39 | # pragma once
|
---|
| 40 | #endif
|
---|
[1] | 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 |
|
---|
[35152] | 51 |
|
---|
[20374] | 52 | RT_C_DECLS_BEGIN
|
---|
[1] | 53 |
|
---|
[38547] | 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
|
---|
[1] | 64 |
|
---|
[38547] | 65 |
|
---|
[1] | 66 | /**
|
---|
[46161] | 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 |
|
---|
[51770] | 147 | /** Pointer to a loader reader instance. */
|
---|
| 148 | typedef struct RTLDRREADER *PRTLDRREADER;
|
---|
[46161] | 149 | /**
|
---|
[51770] | 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 | */
|
---|
[85121] | 173 | DECLCALLBACKMEMBER(int, pfnRead,(PRTLDRREADER pReader, void *pvBuf, size_t cb, RTFOFF off));
|
---|
[51770] | 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 | */
|
---|
[85121] | 181 | DECLCALLBACKMEMBER(RTFOFF, pfnTell,(PRTLDRREADER pReader));
|
---|
[51770] | 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 | */
|
---|
[85121] | 189 | DECLCALLBACKMEMBER(uint64_t, pfnSize,(PRTLDRREADER pReader));
|
---|
[51770] | 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 | */
|
---|
[85121] | 202 | DECLCALLBACKMEMBER(int, pfnMap,(PRTLDRREADER pReader, const void **ppvBits));
|
---|
[51770] | 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 | */
|
---|
[85121] | 211 | DECLCALLBACKMEMBER(int, pfnUnmap,(PRTLDRREADER pReader, const void *pvBits));
|
---|
[51770] | 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 | */
|
---|
[85121] | 219 | DECLCALLBACKMEMBER(const char *, pfnLogName,(PRTLDRREADER pReader));
|
---|
[51770] | 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 | */
|
---|
[85121] | 228 | DECLCALLBACKMEMBER(int, pfnDestroy,(PRTLDRREADER pReader));
|
---|
[51770] | 229 | } RTLDRREADER;
|
---|
| 230 |
|
---|
| 231 | /** Magic value for RTLDRREADER (Gordon Matthew Thomas Sumner / Sting). */
|
---|
| 232 | #define RTLDRREADER_MAGIC UINT32_C(0x19511002)
|
---|
| 233 |
|
---|
| 234 |
|
---|
| 235 | /**
|
---|
[11888] | 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 |
|
---|
[17019] | 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);
|
---|
[17010] | 251 |
|
---|
[11888] | 252 | /**
|
---|
[1] | 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 | /**
|
---|
[34959] | 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.
|
---|
[35191] | 285 | * @param fFlags See RTLDRLOAD_FLAGS_XXX.
|
---|
[35183] | 286 | * @param pErrInfo Where to return extended error information. Optional.
|
---|
[34959] | 287 | */
|
---|
[35183] | 288 | RTDECL(int) RTLdrLoadEx(const char *pszFilename, PRTLDRMOD phLdrMod, uint32_t fFlags, PRTERRINFO pErrInfo);
|
---|
[34959] | 289 |
|
---|
[79559] | 290 | /** @defgroup RTLDRLOAD_FLAGS_XXX Flags for RTLdrLoadEx, RTLdrLoadSystemEx and RTLdrGetSystemSymbolEx
|
---|
[35191] | 291 | * @{ */
|
---|
| 292 | /** Symbols defined in this library are not made available to resolve
|
---|
| 293 | * references in subsequently loaded libraries (default). */
|
---|
[56309] | 294 | #define RTLDRLOAD_FLAGS_LOCAL UINT32_C(0)
|
---|
[35191] | 295 | /** Symbols defined in this library will be made available for symbol
|
---|
| 296 | * resolution of subsequently loaded libraries. */
|
---|
[56309] | 297 | #define RTLDRLOAD_FLAGS_GLOBAL RT_BIT_32(0)
|
---|
[46593] | 298 | /** Do not unload the library upon RTLdrClose. (For system libs.) */
|
---|
[56309] | 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)
|
---|
[74253] | 304 | /** Do not append default suffix. */
|
---|
| 305 | #define RTLDRLOAD_FLAGS_NO_SUFFIX RT_BIT_32(3)
|
---|
[79559] | 306 | /** Shift for the first .so.MAJOR version number to try.
|
---|
| 307 | * Only applicable to RTLdrLoadSystemEx() and RTLdrGetSystemSymbolEx(). */
|
---|
[92775] | 308 | #define RTLDRLOAD_FLAGS_SO_VER_BEGIN_SHIFT 12
|
---|
[79559] | 309 | /** Mask for the first .so.MAJOR version number to try.
|
---|
| 310 | * Only applicable to RTLdrLoadSystemEx() and RTLdrGetSystemSymbolEx(). */
|
---|
[92775] | 311 | #define RTLDRLOAD_FLAGS_SO_VER_BEGIN_MASK UINT32_C(0x003ff000)
|
---|
[79559] | 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. */
|
---|
[74253] | 328 | #define RTLDRLOAD_FLAGS_VALID_MASK UINT32_C(0x0000000f)
|
---|
[35191] | 329 | /** @} */
|
---|
| 330 |
|
---|
[34959] | 331 | /**
|
---|
[46593] | 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 | /**
|
---|
[79559] | 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 | /**
|
---|
[46593] | 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.
|
---|
[79559] | 363 | * @param pszSymbol Symbol name.
|
---|
[46593] | 364 | */
|
---|
| 365 | RTDECL(void *) RTLdrGetSystemSymbol(const char *pszFilename, const char *pszSymbol);
|
---|
| 366 |
|
---|
| 367 | /**
|
---|
[79559] | 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 | /**
|
---|
[12423] | 379 | * Loads a dynamic load library (/shared object) image file residing in the
|
---|
| 380 | * RTPathAppPrivateArch() directory.
|
---|
[7279] | 381 | *
|
---|
[12423] | 382 | * Suffix is not required.
|
---|
[7279] | 383 | *
|
---|
| 384 | * @returns iprt status code.
|
---|
[12423] | 385 | * @param pszFilename Image filename. No path.
|
---|
[7279] | 386 | * @param phLdrMod Where to store the handle to the loaded module.
|
---|
| 387 | */
|
---|
[12423] | 388 | RTDECL(int) RTLdrLoadAppPriv(const char *pszFilename, PRTLDRMOD phLdrMod);
|
---|
[7279] | 389 |
|
---|
| 390 | /**
|
---|
[46593] | 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 | /**
|
---|
[16933] | 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,
|
---|
[73442] | 410 | /** 16-bit x86. */
|
---|
| 411 | RTLDRARCH_X86_16,
|
---|
[16933] | 412 | /** 32-bit x86. */
|
---|
| 413 | RTLDRARCH_X86_32,
|
---|
| 414 | /** AMD64 (64-bit x86 if you like). */
|
---|
| 415 | RTLDRARCH_AMD64,
|
---|
[73150] | 416 | /** 32-bit ARM. */
|
---|
| 417 | RTLDRARCH_ARM32,
|
---|
| 418 | /** 64-bit ARM. */
|
---|
| 419 | RTLDRARCH_ARM64,
|
---|
[16933] | 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 |
|
---|
[73150] | 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 |
|
---|
[46023] | 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. */
|
---|
[53818] | 448 | #define RTLDR_O_FOR_DEBUG RT_BIT_32(0)
|
---|
[51770] | 449 | /** Open for signature validation. */
|
---|
[53818] | 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)
|
---|
[83084] | 455 | /** Mach-O: Include the __LINKEDIT segment (ignored by the others). */
|
---|
| 456 | #define RTLDR_O_MACHO_LOAD_LINKEDIT RT_BIT_32(4)
|
---|
[46023] | 457 | /** Mask of valid flags. */
|
---|
[83084] | 458 | #define RTLDR_O_VALID_MASK UINT32_C(0x0000001f)
|
---|
[46023] | 459 | /** @} */
|
---|
| 460 |
|
---|
[16933] | 461 | /**
|
---|
[65239] | 462 | * Open a binary image file.
|
---|
[1] | 463 | *
|
---|
| 464 | * @returns iprt status code.
|
---|
| 465 | * @param pszFilename Image filename.
|
---|
[46023] | 466 | * @param fFlags Valid RTLDR_O_XXX combination.
|
---|
[16933] | 467 | * @param enmArch CPU architecture specifier for the image to be loaded.
|
---|
[1] | 468 | * @param phLdrMod Where to store the handle to the loader module.
|
---|
| 469 | */
|
---|
[16933] | 470 | RTDECL(int) RTLdrOpen(const char *pszFilename, uint32_t fFlags, RTLDRARCH enmArch, PRTLDRMOD phLdrMod);
|
---|
[1] | 471 |
|
---|
| 472 | /**
|
---|
[65239] | 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 | /**
|
---|
[70309] | 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 | /**
|
---|
[51770] | 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);
|
---|
[46080] | 513 |
|
---|
[1] | 514 | /**
|
---|
[46080] | 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.
|
---|
[1] | 522 | */
|
---|
[85121] | 523 | typedef DECLCALLBACKTYPE(int, FNRTLDRRDRMEMREAD,(void *pvBuf, size_t cb, size_t off, void *pvUser));
|
---|
[46080] | 524 | /** Pointer to a RTLdrOpenInMemory reader callback. */
|
---|
| 525 | typedef FNRTLDRRDRMEMREAD *PFNRTLDRRDRMEMREAD;
|
---|
[1] | 526 |
|
---|
| 527 | /**
|
---|
[46080] | 528 | * Called to when the module is unloaded (or done loading) to release resources
|
---|
| 529 | * associated with it (@a pvUser).
|
---|
[1] | 530 | *
|
---|
[46080] | 531 | * @param pvUser The user parameter.
|
---|
[75049] | 532 | * @param cbImage The image size.
|
---|
[1] | 533 | */
|
---|
[85121] | 534 | typedef DECLCALLBACKTYPE(void, FNRTLDRRDRMEMDTOR,(void *pvUser, size_t cbImage));
|
---|
[46080] | 535 | /** Pointer to a RTLdrOpenInMemory destructor callback. */
|
---|
| 536 | typedef FNRTLDRRDRMEMDTOR *PFNRTLDRRDRMEMDTOR;
|
---|
[1] | 537 |
|
---|
| 538 | /**
|
---|
[46080] | 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.
|
---|
[73150] | 556 | * @param pErrInfo Pointer to an error info buffer, optional.
|
---|
[46083] | 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.
|
---|
[46080] | 562 | */
|
---|
| 563 | RTDECL(int) RTLdrOpenInMemory(const char *pszName, uint32_t fFlags, RTLDRARCH enmArch, size_t cbImage,
|
---|
| 564 | PFNRTLDRRDRMEMREAD pfnRead, PFNRTLDRRDRMEMDTOR pfnDtor, void *pvUser,
|
---|
[73150] | 565 | PRTLDRMOD phLdrMod, PRTERRINFO pErrInfo);
|
---|
[46080] | 566 |
|
---|
| 567 | /**
|
---|
[1] | 568 | * Closes a loader module handle.
|
---|
| 569 | *
|
---|
| 570 | * The handle can be obtained using any of the RTLdrLoad(), RTLdrOpen()
|
---|
[46080] | 571 | * and RTLdrOpenInMemory() functions.
|
---|
[1] | 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.
|
---|
[52213] | 582 | * @retval VERR_LDR_FORWARDER forwarder, use pfnQueryForwarderInfo. Buffer size
|
---|
| 583 | * hint in @a ppvValue.
|
---|
[1] | 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.
|
---|
[52213] | 599 | * @retval VERR_LDR_FORWARDER forwarder, use pfnQueryForwarderInfo. Buffer size
|
---|
| 600 | * hint in @a pValue.
|
---|
[1] | 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.
|
---|
[52213] | 607 | * @param iOrdinal Symbol ordinal number, pass UINT32_MAX if pszSymbol
|
---|
| 608 | * should be used instead.
|
---|
[1] | 609 | * @param pszSymbol Symbol name.
|
---|
| 610 | * @param pValue Where to store the symbol value.
|
---|
| 611 | */
|
---|
[52213] | 612 | RTDECL(int) RTLdrGetSymbolEx(RTLDRMOD hLdrMod, const void *pvBits, RTLDRADDR BaseAddress,
|
---|
| 613 | uint32_t iOrdinal, const char *pszSymbol, PRTLDRADDR pValue);
|
---|
[1] | 614 |
|
---|
| 615 | /**
|
---|
[46593] | 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 | /**
|
---|
[52213] | 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 | /**
|
---|
[1] | 668 | * Gets the size of the loaded image.
|
---|
| 669 | *
|
---|
[46080] | 670 | * This is not necessarily available for images that has been loaded using
|
---|
| 671 | * RTLdrLoad().
|
---|
| 672 | *
|
---|
[1] | 673 | * @returns image size (in bytes).
|
---|
[46080] | 674 | * @returns ~(size_t)0 on if not available.
|
---|
[1] | 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 | */
|
---|
[85121] | 690 | typedef DECLCALLBACKTYPE(int, FNRTLDRIMPORT,(RTLDRMOD hLdrMod, const char *pszModule, const char *pszSymbol, unsigned uSymbol,
|
---|
| 691 | PRTLDRADDR pValue, void *pvUser));
|
---|
[1] | 692 | /** Pointer to a FNRTLDRIMPORT() callback function. */
|
---|
[58132] | 693 | typedef FNRTLDRIMPORT *PFNRTLDRIMPORT;
|
---|
[1] | 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 | */
|
---|
[38547] | 708 | RTDECL(int) RTLdrGetBits(RTLDRMOD hLdrMod, void *pvBits, RTLDRADDR BaseAddress, PFNRTLDRIMPORT pfnGetImport, void *pvUser);
|
---|
[1] | 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.
|
---|
[33540] | 717 | * Must have been passed to RTLdrGetBits().
|
---|
[1] | 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 | */
|
---|
[38547] | 724 | RTDECL(int) RTLdrRelocate(RTLDRMOD hLdrMod, void *pvBits, RTLDRADDR NewBaseAddress, RTLDRADDR OldBaseAddress,
|
---|
[1] | 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 | */
|
---|
[85121] | 737 | typedef DECLCALLBACKTYPE(int, FNRTLDRENUMSYMS,(RTLDRMOD hLdrMod, const char *pszSymbol, unsigned uSymbol, RTLDRADDR Value, void *pvUser));
|
---|
[57944] | 738 | /** Pointer to a FNRTLDRENUMSYMS() callback function. */
|
---|
| 739 | typedef FNRTLDRENUMSYMS *PFNRTLDRENUMSYMS;
|
---|
[1] | 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 | */
|
---|
[38547] | 754 | RTDECL(int) RTLdrEnumSymbols(RTLDRMOD hLdrMod, unsigned fFlags, const void *pvBits, RTLDRADDR BaseAddress, PFNRTLDRENUMSYMS pfnCallback, void *pvUser);
|
---|
[1] | 755 |
|
---|
| 756 | /** @name RTLdrEnumSymbols flags.
|
---|
| 757 | * @{ */
|
---|
| 758 | /** Returns ALL kinds of symbols. The default is to only return public/exported symbols. */
|
---|
[70313] | 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)
|
---|
[1] | 762 | /** @} */
|
---|
| 763 |
|
---|
[70313] | 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
|
---|
[38515] | 771 |
|
---|
[70313] | 772 |
|
---|
[38515] | 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,
|
---|
[45994] | 786 | /** Debug With Arbitrary Record Format (DWARF), in external file (DWO). */
|
---|
| 787 | RTLDRDBGINFOTYPE_DWARF_DWO,
|
---|
[38515] | 788 | /** Microsoft Codeview debug info. */
|
---|
| 789 | RTLDRDBGINFOTYPE_CODEVIEW,
|
---|
[45994] | 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,
|
---|
[46273] | 796 | /** Microsoft COFF debug info. */
|
---|
| 797 | RTLDRDBGINFOTYPE_COFF,
|
---|
[38515] | 798 | /** Watcom debug info. */
|
---|
| 799 | RTLDRDBGINFOTYPE_WATCOM,
|
---|
[57926] | 800 | /** IBM High Level Language debug info. */
|
---|
[38515] | 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 |
|
---|
[45994] | 808 |
|
---|
[38515] | 809 | /**
|
---|
[45994] | 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 |
|
---|
[46273] | 847 | /** RTLDRDBGINFOTYPE_CODEVIEW, RTLDRDBGINFOTYPE_COFF */
|
---|
[45994] | 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;
|
---|
[46273] | 858 | } Cv, Coff;
|
---|
[45994] | 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 | /**
|
---|
[38515] | 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.
|
---|
[45994] | 905 | * @param pDbgInfo Pointer to a read only structure with the details.
|
---|
[38515] | 906 | * @param pvUser The user parameter specified to RTLdrEnumDbgInfo.
|
---|
| 907 | */
|
---|
[85121] | 908 | typedef DECLCALLBACKTYPE(int, FNRTLDRENUMDBG,(RTLDRMOD hLdrMod, PCRTLDRDBGINFO pDbgInfo, void *pvUser));
|
---|
[38515] | 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 |
|
---|
[38547] | 926 |
|
---|
| 927 | /**
|
---|
| 928 | * Loader segment.
|
---|
| 929 | */
|
---|
| 930 | typedef struct RTLDRSEG
|
---|
| 931 | {
|
---|
[46266] | 932 | /** The segment name. Always set to something. */
|
---|
| 933 | const char *pszName;
|
---|
[38547] | 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 | */
|
---|
[85121] | 997 | typedef DECLCALLBACKTYPE(int, FNRTLDRENUMSEGS,(RTLDRMOD hLdrMod, PCRTLDRSEG pSeg, void *pvUser));
|
---|
[38547] | 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 |
|
---|
[38581] | 1012 | /**
|
---|
[102276] | 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 | /**
|
---|
[38581] | 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);
|
---|
[38547] | 1035 |
|
---|
[38581] | 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.
|
---|
[57944] | 1053 | * @param iSeg The segment index.
|
---|
[57926] | 1054 | * @param offSeg The segment offset.
|
---|
| 1055 | * @param pRva Where to return the RVA.
|
---|
[38581] | 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.
|
---|
[57926] | 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.
|
---|
[38581] | 1068 | */
|
---|
| 1069 | RTDECL(int) RTLdrRvaToSegOffset(RTLDRMOD hLdrMod, RTLDRADDR Rva, uint32_t *piSeg, PRTLDRADDR poffSeg);
|
---|
| 1070 |
|
---|
[46161] | 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 |
|
---|
[46164] | 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);
|
---|
[46161] | 1106 |
|
---|
[49044] | 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,
|
---|
[51770] | 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,
|
---|
[95612] | 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,
|
---|
[51770] | 1140 |
|
---|
| 1141 | /** Query whether code signature checks are enabled. */
|
---|
| 1142 | RTLDRPROP_SIGNATURE_CHECKS_ENFORCED,
|
---|
| 1143 |
|
---|
[52403] | 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,
|
---|
[64891] | 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,
|
---|
[66367] | 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,
|
---|
[73387] | 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. */
|
---|
[73375] | 1164 | RTLDRPROP_UNWIND_INFO,
|
---|
[89969] | 1165 | /** The image build-id (ELF/GNU).
|
---|
| 1166 | * Returns usually a SHA1 checksum in the buffer. */
|
---|
| 1167 | RTLDRPROP_BUILDID,
|
---|
[52403] | 1168 |
|
---|
[49044] | 1169 | /** End of valid properties. */
|
---|
| 1170 | RTLDRPROP_END,
|
---|
| 1171 | /** Blow the type up to 32 bits. */
|
---|
| 1172 | RTLDRPROP_32BIT_HACK = 0x7fffffff
|
---|
| 1173 | } RTLDRPROP;
|
---|
[46164] | 1174 |
|
---|
[49044] | 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.
|
---|
[51770] | 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.
|
---|
[49044] | 1187 | * @retval VERR_INVALID_HANDLE if the handle is invalid.
|
---|
| 1188 | *
|
---|
| 1189 | * @param hLdrMod The module handle.
|
---|
[57926] | 1190 | * @param enmProp The property to query.
|
---|
[52403] | 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.
|
---|
[49044] | 1194 | */
|
---|
| 1195 | RTDECL(int) RTLdrQueryProp(RTLDRMOD hLdrMod, RTLDRPROP enmProp, void *pvBuf, size_t cbBuf);
|
---|
| 1196 |
|
---|
[51770] | 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.
|
---|
[57926] | 1213 | * @param enmProp The property to query.
|
---|
[52403] | 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.
|
---|
[51770] | 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 | */
|
---|
[57944] | 1225 | RTDECL(int) RTLdrQueryPropEx(RTLDRMOD hLdrMod, RTLDRPROP enmProp, void *pvBits, void *pvBuf, size_t cbBuf, size_t *pcbRet);
|
---|
[51770] | 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 | /**
|
---|
[86549] | 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 | /**
|
---|
[51770] | 1273 | * Callback used by RTLdrVerifySignature to verify the signature and associated
|
---|
| 1274 | * certificates.
|
---|
| 1275 | *
|
---|
[86549] | 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).
|
---|
[51770] | 1283 | * @param hLdrMod The module handle.
|
---|
[86549] | 1284 | * @param pInfo Signature information.
|
---|
[51770] | 1285 | * @param pErrInfo Pointer to an error info buffer, optional.
|
---|
| 1286 | * @param pvUser User argument.
|
---|
| 1287 | */
|
---|
[86549] | 1288 | typedef DECLCALLBACKTYPE(int, FNRTLDRVALIDATESIGNEDDATA,(RTLDRMOD hLdrMod, PCRTLDRSIGNATUREINFO pInfo,
|
---|
[85121] | 1289 | PRTERRINFO pErrInfo, void *pvUser));
|
---|
[51770] | 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.
|
---|
[95612] | 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).
|
---|
[51770] | 1320 | */
|
---|
[95612] | 1321 | RTDECL(int) RTLdrHashImage(RTLDRMOD hLdrMod, RTDIGESTTYPE enmDigest, uint8_t *pabHash, size_t cbHash);
|
---|
[51770] | 1322 |
|
---|
[73494] | 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 | *
|
---|
[73497] | 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.
|
---|
[73494] | 1341 | *
|
---|
| 1342 | * @sa RTDbgModUnwindFrame
|
---|
| 1343 | */
|
---|
| 1344 | RTDECL(int) RTLdrUnwindFrame(RTLDRMOD hLdrMod, void const *pvBits, uint32_t iSeg, RTLDRADDR off, PRTDBGUNWINDSTATE pState);
|
---|
| 1345 |
|
---|
[20374] | 1346 | RT_C_DECLS_END
|
---|
[1] | 1347 |
|
---|
| 1348 | /** @} */
|
---|
| 1349 |
|
---|
[76585] | 1350 | #endif /* !IPRT_INCLUDED_ldr_h */
|
---|
[1] | 1351 |
|
---|