VirtualBox

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

Last change on this file since 103224 was 102276, checked in by vboxsync, 11 months ago

IPRT/ldr: Added RTLdrLxSetSegmentSelectors. bugref:10371

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