VirtualBox

source: vbox/trunk/include/iprt/ldr.h@ 83941

Last change on this file since 83941 was 83084, checked in by vboxsync, 5 years ago

IPRT,DBGPlugInDarwin: Added flags for indicating that the LINKEDIT segment should be loaded in Mach-O images and debug files.

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

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