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