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