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