ldr.h@ 74312

Last change on this file since 74312 was 74253, checked in by vboxsync, 6 years ago
IPRT/ldr: Added RTLDRLOAD_FLAGS_NO_SUFFIX flag for enabling loading frameworks on darwin.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 47.0 KB

Line
1	/** @file
2	* IPRT - Loader.
3	*/
4
5	/*
6	* Copyright (C) 2006-2017 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	/** Windows/NT: Search the DLL load directory for imported DLLs - W7,
288	* Vista, and W2K8 requires KB2533623 to be installed to support this; not
289	* supported on XP, W2K3 or earlier. Ignored on other platforms. */
290	#define RTLDRLOAD_FLAGS_NT_SEARCH_DLL_LOAD_DIR RT_BIT_32(2)
291	/** Do not append default suffix. */
292	#define RTLDRLOAD_FLAGS_NO_SUFFIX RT_BIT_32(3)
293	/** The mask of valid flag bits. */
294	#define RTLDRLOAD_FLAGS_VALID_MASK UINT32_C(0x0000000f)
295	/** @} */
296
297	/**
298	* Loads a dynamic load library (/shared object) image file residing in one of
299	* the default system library locations.
300	*
301	* Only the system library locations are searched. No suffix is required.
302	*
303	* @returns iprt status code.
304	* @param pszFilename Image filename. No path.
305	* @param fNoUnload Do not unload the library when RTLdrClose is called.
306	* @param phLdrMod Where to store the handle to the loaded module.
307	*/
308	RTDECL(int) RTLdrLoadSystem(const char *pszFilename, bool fNoUnload, PRTLDRMOD phLdrMod);
309
310	/**
311	* Combines RTLdrLoadSystem and RTLdrGetSymbol, with fNoUnload set to true.
312	*
313	* @returns The symbol value, NULL on failure. (If you care for a less boolean
314	* status, go thru the necessary API calls yourself.)
315	* @param pszFilename Image filename. No path.
316	* @param pszSymbol Symbol name.
317	*/
318	RTDECL(void ) RTLdrGetSystemSymbol(const char pszFilename, const char *pszSymbol);
319
320	/**
321	* Loads a dynamic load library (/shared object) image file residing in the
322	* RTPathAppPrivateArch() directory.
323	*
324	* Suffix is not required.
325	*
326	* @returns iprt status code.
327	* @param pszFilename Image filename. No path.
328	* @param phLdrMod Where to store the handle to the loaded module.
329	*/
330	RTDECL(int) RTLdrLoadAppPriv(const char *pszFilename, PRTLDRMOD phLdrMod);
331
332	/**
333	* Gets the native module handle for a module loaded by RTLdrLoad, RTLdrLoadEx,
334	* RTLdrLoadSystem, or RTLdrLoadAppPriv.
335	*
336	* @returns Native handle on success, ~(uintptr_t)0 on failure.
337	* @param hLdrMod The loader module handle.
338	*/
339	RTDECL(uintptr_t) RTLdrGetNativeHandle(RTLDRMOD hLdrMod);
340
341
342	/**
343	* Image architecuture specifier for RTLdrOpenEx.
344	*/
345	typedef enum RTLDRARCH
346	{
347	RTLDRARCH_INVALID = 0,
348	/** Whatever. */
349	RTLDRARCH_WHATEVER,
350	/** The host architecture. */
351	RTLDRARCH_HOST,
352	/** 16-bit x86. */
353	RTLDRARCH_X86_16,
354	/** 32-bit x86. */
355	RTLDRARCH_X86_32,
356	/** AMD64 (64-bit x86 if you like). */
357	RTLDRARCH_AMD64,
358	/** 32-bit ARM. */
359	RTLDRARCH_ARM32,
360	/** 64-bit ARM. */
361	RTLDRARCH_ARM64,
362	/** End of the valid values. */
363	RTLDRARCH_END,
364	/** Make sure the type is a full 32-bit. */
365	RTLDRARCH_32BIT_HACK = 0x7fffffff
366	} RTLDRARCH;
367	/** Pointer to a RTLDRARCH. */
368	typedef RTLDRARCH *PRTLDRARCH;
369
370	/**
371	* Translates a RTLDRARCH value to a string.
372	*
373	* @returns Name corresponding to @a enmArch
374	* @param enmArch The value to name.
375	*/
376	RTDECL(const char *) RTLdrArchName(RTLDRARCH enmArch);
377
378	/**
379	* Returns the host architecture.
380	*
381	* @returns Host architecture or RTLDRARCH_WHATEVER if no match.
382	*/
383	RTDECL(RTLDRARCH) RTLdrGetHostArch(void);
384
385
386	/** @name RTLDR_O_XXX - RTLdrOpen flags.
387	* @{ */
388	/** Open for debugging or introspection reasons.
389	* This will skip a few of the stricter validations when loading images. */
390	#define RTLDR_O_FOR_DEBUG RT_BIT_32(0)
391	/** Open for signature validation. */
392	#define RTLDR_O_FOR_VALIDATION RT_BIT_32(1)
393	/** The arch specification is just a guideline for FAT binaries. */
394	#define RTLDR_O_WHATEVER_ARCH RT_BIT_32(2)
395	/** Ignore the architecture specification if there is no code. */
396	#define RTLDR_O_IGNORE_ARCH_IF_NO_CODE RT_BIT_32(3)
397	/** Mask of valid flags. */
398	#define RTLDR_O_VALID_MASK UINT32_C(0x0000000f)
399	/** @} */
400
401	/**
402	* Open a binary image file.
403	*
404	* @returns iprt status code.
405	* @param pszFilename Image filename.
406	* @param fFlags Valid RTLDR_O_XXX combination.
407	* @param enmArch CPU architecture specifier for the image to be loaded.
408	* @param phLdrMod Where to store the handle to the loader module.
409	*/
410	RTDECL(int) RTLdrOpen(const char *pszFilename, uint32_t fFlags, RTLDRARCH enmArch, PRTLDRMOD phLdrMod);
411
412	/**
413	* Open a binary image file, extended version.
414	*
415	* @returns iprt status code.
416	* @param pszFilename Image filename.
417	* @param fFlags Valid RTLDR_O_XXX combination.
418	* @param enmArch CPU architecture specifier for the image to be loaded.
419	* @param phLdrMod Where to store the handle to the loader module.
420	* @param pErrInfo Where to return extended error information. Optional.
421	*/
422	RTDECL(int) RTLdrOpenEx(const char *pszFilename, uint32_t fFlags, RTLDRARCH enmArch, PRTLDRMOD phLdrMod, PRTERRINFO pErrInfo);
423
424	/**
425	* Opens a binary image file using kLdr.
426	*
427	* @returns iprt status code.
428	* @param pszFilename Image filename.
429	* @param phLdrMod Where to store the handle to the loaded module.
430	* @param fFlags Valid RTLDR_O_XXX combination.
431	* @param enmArch CPU architecture specifier for the image to be loaded.
432	* @remark Primarily for testing the loader.
433	*/
434	RTDECL(int) RTLdrOpenkLdr(const char *pszFilename, uint32_t fFlags, RTLDRARCH enmArch, PRTLDRMOD phLdrMod);
435
436	/**
437	* Open a binary image file allowing VFS chains in the filename.
438	*
439	* @returns iprt status code.
440	* @param pszFilename Image filename, VFS chain specifiers allowed.
441	* @param fFlags Valid RTLDR_O_XXX combination.
442	* @param enmArch CPU architecture specifier for the image to be loaded.
443	* @param phLdrMod Where to store the handle to the loader module.
444	* @param poffError Where to return the offset into @a pszFilename of an VFS
445	* chain element causing trouble. Optional.
446	* @param pErrInfo Where to return extended error information. Optional.
447	*/
448	RTDECL(int) RTLdrOpenVfsChain(const char *pszFilename, uint32_t fFlags, RTLDRARCH enmArch,
449	PRTLDRMOD phLdrMod, uint32_t *poffError, PRTERRINFO pErrInfo);
450
451	/**
452	* Open a binary image file using kLdr allowing VFS chains in the filename.
453	*
454	* @returns iprt status code.
455	* @param pszFilename Image filename.
456	* @param fFlags Reserved, MBZ.
457	* @param enmArch CPU architecture specifier for the image to be loaded.
458	* @param phLdrMod Where to store the handle to the loaded module.
459	* @param poffError Where to return the offset into @a pszFilename of an VFS
460	* chain element causing trouble. Optional.
461	* @param pErrInfo Where to return extended error information. Optional.
462	* @remark Primarily for testing the loader.
463	*/
464	RTDECL(int) RTLdrOpenVfsChainkLdr(const char *pszFilename, uint32_t fFlags, RTLDRARCH enmArch,
465	PRTLDRMOD phLdrMod, uint32_t *poffError, PRTERRINFO pErrInfo);
466
467	/**
468	* Open part with reader.
469	*
470	* @returns iprt status code.
471	* @param pReader The loader reader instance which will provide the raw
472	* image bits. The reader instance will be consumed on
473	* success. On failure, the caller has to do the cleaning
474	* up.
475	* @param fFlags Valid RTLDR_O_XXX combination.
476	* @param enmArch Architecture specifier.
477	* @param phMod Where to store the handle.
478	* @param pErrInfo Where to return extended error information. Optional.
479	*/
480	RTDECL(int) RTLdrOpenWithReader(PRTLDRREADER pReader, uint32_t fFlags, RTLDRARCH enmArch, PRTLDRMOD phMod, PRTERRINFO pErrInfo);
481
482	/**
483	* Called to read @a cb bytes at @a off into @a pvBuf.
484	*
485	* @returns IPRT status code
486	* @param pvBuf The output buffer.
487	* @param cb The number of bytes to read.
488	* @param off Where to start reading.
489	* @param pvUser The user parameter.
490	*/
491	typedef DECLCALLBACK(int) FNRTLDRRDRMEMREAD(void pvBuf, size_t cb, size_t off, void pvUser);
492	/** Pointer to a RTLdrOpenInMemory reader callback. */
493	typedef FNRTLDRRDRMEMREAD *PFNRTLDRRDRMEMREAD;
494
495	/**
496	* Called to when the module is unloaded (or done loading) to release resources
497	* associated with it (@a pvUser).
498	*
499	* @returns IPRT status code
500	* @param pvUser The user parameter.
501	*/
502	typedef DECLCALLBACK(void) FNRTLDRRDRMEMDTOR(void *pvUser);
503	/** Pointer to a RTLdrOpenInMemory destructor callback. */
504	typedef FNRTLDRRDRMEMDTOR *PFNRTLDRRDRMEMDTOR;
505
506	/**
507	* Open a in-memory image or an image with a custom reader callback.
508	*
509	* @returns IPRT status code.
510	* @param pszName The image name.
511	* @param fFlags Valid RTLDR_O_XXX combination.
512	* @param enmArch CPU architecture specifier for the image to be loaded.
513	* @param cbImage The size of the image (fake file).
514	* @param pfnRead The read function. If NULL is passed in, a default
515	* reader function is provided that assumes @a pvUser
516	* points to the raw image bits, at least @a cbImage of
517	* valid memory.
518	* @param pfnDtor The destructor function. If NULL is passed, a default
519	* destructor will be provided that passes @a pvUser to
520	* RTMemFree.
521	* @param pvUser The user argument or, if any of the callbacks are NULL,
522	* a pointer to a memory block.
523	* @param phLdrMod Where to return the module handle.
524	* @param pErrInfo Pointer to an error info buffer, optional.
525	*
526	* @remarks With the exception of invalid @a pfnDtor and/or @a pvUser
527	* parameters, the pfnDtor methods (or the default one if NULL) will
528	* always be invoked. The destruction of pvUser is entirely in the
529	* hands of this method once it's called.
530	*/
531	RTDECL(int) RTLdrOpenInMemory(const char *pszName, uint32_t fFlags, RTLDRARCH enmArch, size_t cbImage,
532	PFNRTLDRRDRMEMREAD pfnRead, PFNRTLDRRDRMEMDTOR pfnDtor, void *pvUser,
533	PRTLDRMOD phLdrMod, PRTERRINFO pErrInfo);
534
535	/**
536	* Closes a loader module handle.
537	*
538	* The handle can be obtained using any of the RTLdrLoad(), RTLdrOpen()
539	* and RTLdrOpenInMemory() functions.
540	*
541	* @returns iprt status code.
542	* @param hLdrMod The loader module handle.
543	*/
544	RTDECL(int) RTLdrClose(RTLDRMOD hLdrMod);
545
546	/**
547	* Gets the address of a named exported symbol.
548	*
549	* @returns iprt status code.
550	* @retval VERR_LDR_FORWARDER forwarder, use pfnQueryForwarderInfo. Buffer size
551	* hint in @a ppvValue.
552	* @param hLdrMod The loader module handle.
553	* @param pszSymbol Symbol name.
554	* @param ppvValue Where to store the symbol value. Note that this is restricted to the
555	* pointer size used on the host!
556	*/
557	RTDECL(int) RTLdrGetSymbol(RTLDRMOD hLdrMod, const char pszSymbol, void *ppvValue);
558
559	/**
560	* Gets the address of a named exported symbol.
561	*
562	* This function differs from the plain one in that it can deal with
563	* both GC and HC address sizes, and that it can calculate the symbol
564	* value relative to any given base address.
565	*
566	* @returns iprt status code.
567	* @retval VERR_LDR_FORWARDER forwarder, use pfnQueryForwarderInfo. Buffer size
568	* hint in @a pValue.
569	* @param hLdrMod The loader module handle.
570	* @param pvBits Optional pointer to the loaded image.
571	* Set this to NULL if no RTLdrGetBits() processed image bits are available.
572	* Not supported for RTLdrLoad() images.
573	* @param BaseAddress Image load address.
574	* Not supported for RTLdrLoad() images.
575	* @param iOrdinal Symbol ordinal number, pass UINT32_MAX if pszSymbol
576	* should be used instead.
577	* @param pszSymbol Symbol name.
578	* @param pValue Where to store the symbol value.
579	*/
580	RTDECL(int) RTLdrGetSymbolEx(RTLDRMOD hLdrMod, const void *pvBits, RTLDRADDR BaseAddress,
581	uint32_t iOrdinal, const char *pszSymbol, PRTLDRADDR pValue);
582
583	/**
584	* Gets the address of a named exported function.
585	*
586	* Same as RTLdrGetSymbol, but skips the status code and pointer to return
587	* variable stuff.
588	*
589	* @returns Pointer to the function if found, NULL if not.
590	* @param hLdrMod The loader module handle.
591	* @param pszSymbol Function name.
592	*/
593	RTDECL(PFNRT) RTLdrGetFunction(RTLDRMOD hLdrMod, const char *pszSymbol);
594
595	/**
596	* Information about an imported symbol.
597	*/
598	typedef struct RTLDRIMPORTINFO
599	{
600	/** Symbol table entry number, UINT32_MAX if not available. */
601	uint32_t iSelfOrdinal;
602	/** The ordinal of the imported symbol in szModule, UINT32_MAX if not used. */
603	uint32_t iOrdinal;
604	/** The symbol name, NULL if not used. This points to the char immediately
605	* following szModule when returned by RTLdrQueryForwarderInfo. */
606	const char *pszSymbol;
607	/** The name of the module being imported from. */
608	char szModule[1];
609	} RTLDRIMPORTINFO;
610	/** Pointer to information about an imported symbol. */
611	typedef RTLDRIMPORTINFO *PRTLDRIMPORTINFO;
612	/** Pointer to const information about an imported symbol. */
613	typedef RTLDRIMPORTINFO const *PCRTLDRIMPORTINFO;
614
615	/**
616	* Query information about a forwarded symbol.
617	*
618	* @returns IPRT status code.
619	* @param hLdrMod The loader module handle.
620	* @param pvBits Optional pointer to the loaded image.
621	* Set this to NULL if no RTLdrGetBits() processed image bits are available.
622	* Not supported for RTLdrLoad() images.
623	* @param iOrdinal Symbol ordinal number, pass UINT32_MAX if pszSymbol
624	* should be used instead.
625	* @param pszSymbol Symbol name.
626	* @param pInfo Where to return the forwarder info.
627	* @param cbInfo Size of the buffer @a pInfo points to. For a size
628	* hint, see @a pValue when RTLdrGetSymbolEx returns
629	* VERR_LDR_FORWARDER.
630	*/
631	RTDECL(int) RTLdrQueryForwarderInfo(RTLDRMOD hLdrMod, const void pvBits, uint32_t iOrdinal, const char pszSymbol,
632	PRTLDRIMPORTINFO pInfo, size_t cbInfo);
633
634
635	/**
636	* Gets the size of the loaded image.
637	*
638	* This is not necessarily available for images that has been loaded using
639	* RTLdrLoad().
640	*
641	* @returns image size (in bytes).
642	* @returns ~(size_t)0 on if not available.
643	* @param hLdrMod Handle to the loader module.
644	*/
645	RTDECL(size_t) RTLdrSize(RTLDRMOD hLdrMod);
646
647	/**
648	* Resolve an external symbol during RTLdrGetBits().
649	*
650	* @returns iprt status code.
651	* @param hLdrMod The loader module handle.
652	* @param pszModule Module name.
653	* @param pszSymbol Symbol name, NULL if uSymbol should be used.
654	* @param uSymbol Symbol ordinal, ~0 if pszSymbol should be used.
655	* @param pValue Where to store the symbol value (address).
656	* @param pvUser User argument.
657	*/
658	typedef DECLCALLBACK(int) FNRTLDRIMPORT(RTLDRMOD hLdrMod, const char pszModule, const char pszSymbol, unsigned uSymbol,
659	PRTLDRADDR pValue, void *pvUser);
660	/** Pointer to a FNRTLDRIMPORT() callback function. */
661	typedef FNRTLDRIMPORT *PFNRTLDRIMPORT;
662
663	/**
664	* Loads the image into a buffer provided by the user and applies fixups
665	* for the given base address.
666	*
667	* @returns iprt status code.
668	* @param hLdrMod The load module handle.
669	* @param pvBits Where to put the bits.
670	* Must be as large as RTLdrSize() suggests.
671	* @param BaseAddress The base address.
672	* @param pfnGetImport Callback function for resolving imports one by one.
673	* @param pvUser User argument for the callback.
674	* @remark Not supported for RTLdrLoad() images.
675	*/
676	RTDECL(int) RTLdrGetBits(RTLDRMOD hLdrMod, void pvBits, RTLDRADDR BaseAddress, PFNRTLDRIMPORT pfnGetImport, void pvUser);
677
678	/**
679	* Relocates bits after getting them.
680	* Useful for code which moves around a bit.
681	*
682	* @returns iprt status code.
683	* @param hLdrMod The loader module handle.
684	* @param pvBits Where the image bits are.
685	* Must have been passed to RTLdrGetBits().
686	* @param NewBaseAddress The new base address.
687	* @param OldBaseAddress The old base address.
688	* @param pfnGetImport Callback function for resolving imports one by one.
689	* @param pvUser User argument for the callback.
690	* @remark Not supported for RTLdrLoad() images.
691	*/
692	RTDECL(int) RTLdrRelocate(RTLDRMOD hLdrMod, void *pvBits, RTLDRADDR NewBaseAddress, RTLDRADDR OldBaseAddress,
693	PFNRTLDRIMPORT pfnGetImport, void *pvUser);
694
695	/**
696	* Enumeration callback function used by RTLdrEnumSymbols().
697	*
698	* @returns iprt status code. Failure will stop the enumeration.
699	* @param hLdrMod The loader module handle.
700	* @param pszSymbol Symbol name. NULL if ordinal only.
701	* @param uSymbol Symbol ordinal, ~0 if not used.
702	* @param Value Symbol value.
703	* @param pvUser The user argument specified to RTLdrEnumSymbols().
704	*/
705	typedef DECLCALLBACK(int) FNRTLDRENUMSYMS(RTLDRMOD hLdrMod, const char pszSymbol, unsigned uSymbol, RTLDRADDR Value, void pvUser);
706	/** Pointer to a FNRTLDRENUMSYMS() callback function. */
707	typedef FNRTLDRENUMSYMS *PFNRTLDRENUMSYMS;
708
709	/**
710	* Enumerates all symbols in a module.
711	*
712	* @returns iprt status code.
713	* @param hLdrMod The loader module handle.
714	* @param fFlags Flags indicating what to return and such.
715	* @param pvBits Optional pointer to the loaded image. (RTLDR_ENUM_SYMBOL_FLAGS_*)
716	* Set this to NULL if no RTLdrGetBits() processed image bits are available.
717	* @param BaseAddress Image load address.
718	* @param pfnCallback Callback function.
719	* @param pvUser User argument for the callback.
720	* @remark Not supported for RTLdrLoad() images.
721	*/
722	RTDECL(int) RTLdrEnumSymbols(RTLDRMOD hLdrMod, unsigned fFlags, const void pvBits, RTLDRADDR BaseAddress, PFNRTLDRENUMSYMS pfnCallback, void pvUser);
723
724	/** @name RTLdrEnumSymbols flags.
725	* @{ */
726	/** Returns ALL kinds of symbols. The default is to only return public/exported symbols. */
727	#define RTLDR_ENUM_SYMBOL_FLAGS_ALL RT_BIT(1)
728	/** Ignore forwarders rather than reporting them with RTLDR_ENUM_SYMBOL_FWD_ADDRESS as value. */
729	#define RTLDR_ENUM_SYMBOL_FLAGS_NO_FWD RT_BIT(2)
730	/** @} */
731
732	/** Special symbol for forwarder symbols, since they cannot be resolved with
733	* the current API. */
734	#if (HC_ARCH_BITS == 64 \|\| GC_ARCH_BITS == 64)
735	# define RTLDR_ENUM_SYMBOL_FWD_ADDRESS UINT64_C(0xff4242fffd4242fd)
736	#else
737	# define RTLDR_ENUM_SYMBOL_FWD_ADDRESS UINT32_C(0xff4242fd)
738	#endif
739
740
741	/**
742	* Debug info type (as far the loader can tell).
743	*/
744	typedef enum RTLDRDBGINFOTYPE
745	{
746	/** The invalid 0 value. */
747	RTLDRDBGINFOTYPE_INVALID = 0,
748	/** Unknown debug info format. */
749	RTLDRDBGINFOTYPE_UNKNOWN,
750	/** Stabs. */
751	RTLDRDBGINFOTYPE_STABS,
752	/** Debug With Arbitrary Record Format (DWARF). */
753	RTLDRDBGINFOTYPE_DWARF,
754	/** Debug With Arbitrary Record Format (DWARF), in external file (DWO). */
755	RTLDRDBGINFOTYPE_DWARF_DWO,
756	/** Microsoft Codeview debug info. */
757	RTLDRDBGINFOTYPE_CODEVIEW,
758	/** Microsoft Codeview debug info, in external v2.0+ program database (PDB). */
759	RTLDRDBGINFOTYPE_CODEVIEW_PDB20,
760	/** Microsoft Codeview debug info, in external v7.0+ program database (PDB). */
761	RTLDRDBGINFOTYPE_CODEVIEW_PDB70,
762	/** Microsoft Codeview debug info, in external file (DBG). */
763	RTLDRDBGINFOTYPE_CODEVIEW_DBG,
764	/** Microsoft COFF debug info. */
765	RTLDRDBGINFOTYPE_COFF,
766	/** Watcom debug info. */
767	RTLDRDBGINFOTYPE_WATCOM,
768	/** IBM High Level Language debug info. */
769	RTLDRDBGINFOTYPE_HLL,
770	/** The end of the valid debug info values (exclusive). */
771	RTLDRDBGINFOTYPE_END,
772	/** Blow the type up to 32-bits. */
773	RTLDRDBGINFOTYPE_32BIT_HACK = 0x7fffffff
774	} RTLDRDBGINFOTYPE;
775
776
777	/**
778	* Debug info details for the enumeration callback.
779	*/
780	typedef struct RTLDRDBGINFO
781	{
782	/** The kind of debug info. */
783	RTLDRDBGINFOTYPE enmType;
784	/** The debug info ordinal number / id. */
785	uint32_t iDbgInfo;
786	/** The file offset if this type has one specific location in the executable
787	* image file. This is -1 if there isn't any specific file location. */
788	RTFOFF offFile;
789	/** The link address of the debug info if it's loadable. NIL_RTLDRADDR if not
790	* loadable*/
791	RTLDRADDR LinkAddress;
792	/** The size of the debug information. -1 is used if this isn't applicable.*/
793	RTLDRADDR cb;
794	/** This is set if the debug information is found in an external file. NULL
795	* if no external file involved.
796	* @note Putting it outside the union to allow lazy callback implementation. */
797	const char *pszExtFile;
798	/** Type (enmType) specific information. */
799	union
800	{
801	/** RTLDRDBGINFOTYPE_DWARF */
802	struct
803	{
804	/** The section name. */
805	const char *pszSection;
806	} Dwarf;
807
808	/** RTLDRDBGINFOTYPE_DWARF_DWO */
809	struct
810	{
811	/** The CRC32 of the external file. */
812	uint32_t uCrc32;
813	} Dwo;
814
815	/** RTLDRDBGINFOTYPE_CODEVIEW, RTLDRDBGINFOTYPE_COFF */
816	struct
817	{
818	/** The PE image size. */
819	uint32_t cbImage;
820	/** The timestamp. */
821	uint32_t uTimestamp;
822	/** The major version from the entry. */
823	uint32_t uMajorVer;
824	/** The minor version from the entry. */
825	uint32_t uMinorVer;
826	} Cv, Coff;
827
828	/** RTLDRDBGINFOTYPE_CODEVIEW_DBG */
829	struct
830	{
831	/** The PE image size. */
832	uint32_t cbImage;
833	/** The timestamp. */
834	uint32_t uTimestamp;
835	} Dbg;
836
837	/** RTLDRDBGINFOTYPE_CODEVIEW_PDB20*/
838	struct
839	{
840	/** The PE image size. */
841	uint32_t cbImage;
842	/** The timestamp. */
843	uint32_t uTimestamp;
844	/** The PDB age. */
845	uint32_t uAge;
846	} Pdb20;
847
848	/** RTLDRDBGINFOTYPE_CODEVIEW_PDB70 */
849	struct
850	{
851	/** The PE image size. */
852	uint32_t cbImage;
853	/** The PDB age. */
854	uint32_t uAge;
855	/** The UUID. */
856	RTUUID Uuid;
857	} Pdb70;
858	} u;
859	} RTLDRDBGINFO;
860	/** Pointer to debug info details. */
861	typedef RTLDRDBGINFO *PRTLDRDBGINFO;
862	/** Pointer to read only debug info details. */
863	typedef RTLDRDBGINFO const *PCRTLDRDBGINFO;
864
865
866	/**
867	* Debug info enumerator callback.
868	*
869	* @returns VINF_SUCCESS to continue the enumeration. Any other status code
870	* will cause RTLdrEnumDbgInfo to immediately return with that status.
871	*
872	* @param hLdrMod The module handle.
873	* @param pDbgInfo Pointer to a read only structure with the details.
874	* @param pvUser The user parameter specified to RTLdrEnumDbgInfo.
875	*/
876	typedef DECLCALLBACK(int) FNRTLDRENUMDBG(RTLDRMOD hLdrMod, PCRTLDRDBGINFO pDbgInfo, void *pvUser);
877	/** Pointer to a debug info enumerator callback. */
878	typedef FNRTLDRENUMDBG *PFNRTLDRENUMDBG;
879
880	/**
881	* Enumerate the debug info contained in the executable image.
882	*
883	* @returns IPRT status code or whatever pfnCallback returns.
884	*
885	* @param hLdrMod The module handle.
886	* @param pvBits Optional pointer to bits returned by
887	* RTLdrGetBits(). This can be used by some module
888	* interpreters to reduce memory consumption.
889	* @param pfnCallback The callback function.
890	* @param pvUser The user argument.
891	*/
892	RTDECL(int) RTLdrEnumDbgInfo(RTLDRMOD hLdrMod, const void pvBits, PFNRTLDRENUMDBG pfnCallback, void pvUser);
893
894
895	/**
896	* Loader segment.
897	*/
898	typedef struct RTLDRSEG
899	{
900	/** The segment name. Always set to something. */
901	const char *pszName;
902	/** The length of the segment name. */
903	uint32_t cchName;
904	/** The flat selector to use for the segment (i.e. data/code).
905	* Primarily a way for the user to specify selectors for the LX/LE and NE interpreters. */
906	uint16_t SelFlat;
907	/** The 16-bit selector to use for the segment.
908	* Primarily a way for the user to specify selectors for the LX/LE and NE interpreters. */
909	uint16_t Sel16bit;
910	/** Segment flags. */
911	uint32_t fFlags;
912	/** The segment protection (RTMEM_PROT_XXX). */
913	uint32_t fProt;
914	/** The size of the segment. */
915	RTLDRADDR cb;
916	/** The required segment alignment.
917	* The to 0 if the segment isn't supposed to be mapped. */
918	RTLDRADDR Alignment;
919	/** The link address.
920	* Set to NIL_RTLDRADDR if the segment isn't supposed to be mapped or if
921	* the image doesn't have link addresses. */
922	RTLDRADDR LinkAddress;
923	/** File offset of the segment.
924	* Set to -1 if no file backing (like BSS). */
925	RTFOFF offFile;
926	/** Size of the file bits of the segment.
927	* Set to -1 if no file backing (like BSS). */
928	RTFOFF cbFile;
929	/** The relative virtual address when mapped.
930	* Set to NIL_RTLDRADDR if the segment isn't supposed to be mapped. */
931	RTLDRADDR RVA;
932	/** The size of the segment including the alignment gap up to the next segment when mapped.
933	* This is set to NIL_RTLDRADDR if not implemented. */
934	RTLDRADDR cbMapped;
935	} RTLDRSEG;
936	/** Pointer to a loader segment. */
937	typedef RTLDRSEG *PRTLDRSEG;
938	/** Pointer to a read only loader segment. */
939	typedef RTLDRSEG const *PCRTLDRSEG;
940
941
942	/** @name Segment flags
943	* @{ */
944	/** The segment is 16-bit. When not set the default of the target architecture is assumed. */
945	#define RTLDRSEG_FLAG_16BIT UINT32_C(1)
946	/** The segment requires a 16-bit selector alias. (OS/2) */
947	#define RTLDRSEG_FLAG_OS2_ALIAS16 UINT32_C(2)
948	/** Conforming segment (x86 weirdness). (OS/2) */
949	#define RTLDRSEG_FLAG_OS2_CONFORM UINT32_C(4)
950	/** IOPL (ring-2) segment. (OS/2) */
951	#define RTLDRSEG_FLAG_OS2_IOPL UINT32_C(8)
952	/** @} */
953
954	/**
955	* Segment enumerator callback.
956	*
957	* @returns VINF_SUCCESS to continue the enumeration. Any other status code
958	* will cause RTLdrEnumSegments to immediately return with that
959	* status.
960	*
961	* @param hLdrMod The module handle.
962	* @param pSeg The segment information.
963	* @param pvUser The user parameter specified to RTLdrEnumSegments.
964	*/
965	typedef DECLCALLBACK(int) FNRTLDRENUMSEGS(RTLDRMOD hLdrMod, PCRTLDRSEG pSeg, void *pvUser);
966	/** Pointer to a segment enumerator callback. */
967	typedef FNRTLDRENUMSEGS *PFNRTLDRENUMSEGS;
968
969	/**
970	* Enumerate the debug info contained in the executable image.
971	*
972	* @returns IPRT status code or whatever pfnCallback returns.
973	*
974	* @param hLdrMod The module handle.
975	* @param pfnCallback The callback function.
976	* @param pvUser The user argument.
977	*/
978	RTDECL(int) RTLdrEnumSegments(RTLDRMOD hLdrMod, PFNRTLDRENUMSEGS pfnCallback, void *pvUser);
979
980	/**
981	* Converts a link address to a segment:offset address.
982	*
983	* @returns IPRT status code.
984	*
985	* @param hLdrMod The module handle.
986	* @param LinkAddress The link address to convert.
987	* @param piSeg Where to return the segment index.
988	* @param poffSeg Where to return the segment offset.
989	*/
990	RTDECL(int) RTLdrLinkAddressToSegOffset(RTLDRMOD hLdrMod, RTLDRADDR LinkAddress, uint32_t *piSeg, PRTLDRADDR poffSeg);
991
992	/**
993	* Converts a link address to an image relative virtual address (RVA).
994	*
995	* @returns IPRT status code.
996	*
997	* @param hLdrMod The module handle.
998	* @param LinkAddress The link address to convert.
999	* @param pRva Where to return the RVA.
1000	*/
1001	RTDECL(int) RTLdrLinkAddressToRva(RTLDRMOD hLdrMod, RTLDRADDR LinkAddress, PRTLDRADDR pRva);
1002
1003	/**
1004	* Converts an image relative virtual address (RVA) to a segment:offset.
1005	*
1006	* @returns IPRT status code.
1007	*
1008	* @param hLdrMod The module handle.
1009	* @param iSeg The segment index.
1010	* @param offSeg The segment offset.
1011	* @param pRva Where to return the RVA.
1012	*/
1013	RTDECL(int) RTLdrSegOffsetToRva(RTLDRMOD hLdrMod, uint32_t iSeg, RTLDRADDR offSeg, PRTLDRADDR pRva);
1014
1015	/**
1016	* Converts a segment:offset into an image relative virtual address (RVA).
1017	*
1018	* @returns IPRT status code.
1019	*
1020	* @param hLdrMod The module handle.
1021	* @param Rva The link address to convert.
1022	* @param piSeg Where to return the segment index.
1023	* @param poffSeg Where to return the segment offset.
1024	*/
1025	RTDECL(int) RTLdrRvaToSegOffset(RTLDRMOD hLdrMod, RTLDRADDR Rva, uint32_t *piSeg, PRTLDRADDR poffSeg);
1026
1027	/**
1028	* Gets the image format.
1029	*
1030	* @returns Valid image format on success. RTLDRFMT_INVALID on invalid handle or
1031	* other errors.
1032	* @param hLdrMod The module handle.
1033	*/
1034	RTDECL(RTLDRFMT) RTLdrGetFormat(RTLDRMOD hLdrMod);
1035
1036	/**
1037	* Gets the image type.
1038	*
1039	* @returns Valid image type value on success. RTLDRTYPE_INVALID on
1040	* invalid handle or other errors.
1041	* @param hLdrMod The module handle.
1042	*/
1043	RTDECL(RTLDRTYPE) RTLdrGetType(RTLDRMOD hLdrMod);
1044
1045	/**
1046	* Gets the image endian-ness.
1047	*
1048	* @returns Valid image endian value on success. RTLDRENDIAN_INVALID on invalid
1049	* handle or other errors.
1050	* @param hLdrMod The module handle.
1051	*/
1052	RTDECL(RTLDRENDIAN) RTLdrGetEndian(RTLDRMOD hLdrMod);
1053
1054	/**
1055	* Gets the image endian-ness.
1056	*
1057	* @returns Valid image architecture value on success.
1058	* RTLDRARCH_INVALID on invalid handle or other errors.
1059	* @param hLdrMod The module handle.
1060	*/
1061	RTDECL(RTLDRARCH) RTLdrGetArch(RTLDRMOD hLdrMod);
1062
1063	/**
1064	* Loader properties that can be queried thru RTLdrQueryProp.
1065	*/
1066	typedef enum RTLDRPROP
1067	{
1068	RTLDRPROP_INVALID = 0,
1069	/** The image UUID (Mach-O).
1070	* Returns a RTUUID in the buffer. */
1071	RTLDRPROP_UUID,
1072	/** The image timestamp in seconds, genrally since unix epoc.
1073	* Returns a 32-bit or 64-bit signed integer value in the buffer. */
1074	RTLDRPROP_TIMESTAMP_SECONDS,
1075	/** Checks if the image is signed.
1076	* Returns a bool. */
1077	RTLDRPROP_IS_SIGNED,
1078	/** Retrives the PKCS \#7 SignedData blob that signs the image.
1079	* Returns variable sized buffer containing the ASN.1 BER encoding.
1080	*
1081	* @remarks This generally starts with a PKCS \#7 Content structure, the
1082	* SignedData bit is found a few levels down into this as per RFC. */
1083	RTLDRPROP_PKCS7_SIGNED_DATA,
1084
1085	/** Query whether code signature checks are enabled. */
1086	RTLDRPROP_SIGNATURE_CHECKS_ENFORCED,
1087
1088	/** Number of import or needed modules. */
1089	RTLDRPROP_IMPORT_COUNT,
1090	/** Import module by index (32-bit) stored in the buffer. */
1091	RTLDRPROP_IMPORT_MODULE,
1092	/** The file offset of the main executable header.
1093	* This is mainly for PE, NE and LX headers, but also Mach-O FAT. */
1094	RTLDRPROP_FILE_OFF_HEADER,
1095	/** The internal module name.
1096	* This is the SONAME for ELF, export table name for PE, and zero'th resident
1097	* name table entry for LX.
1098	* Returns zero terminated string. */
1099	RTLDRPROP_INTERNAL_NAME,
1100	/** The raw unwind table if available.
1101	* For PE this means IMAGE_DIRECTORY_ENTRY_EXCEPTION content, for AMD64 this
1102	* is the lookup table (IMAGE_RUNTIME_FUNCTION_ENTRY).
1103	* Not implemented any others yet. */
1104	RTLDRPROP_UNWIND_TABLE,
1105	/** Read unwind info at given RVA and up to buffer size. The RVA is stored
1106	* as uint32_t in the buffer when making the call.
1107	* This is only implemented for PE. */
1108	RTLDRPROP_UNWIND_INFO,
1109
1110	/** End of valid properties. */
1111	RTLDRPROP_END,
1112	/** Blow the type up to 32 bits. */
1113	RTLDRPROP_32BIT_HACK = 0x7fffffff
1114	} RTLDRPROP;
1115
1116	/**
1117	* Generic method for querying image properties.
1118	*
1119	* @returns IPRT status code.
1120	* @retval VERR_NOT_SUPPORTED if the property query isn't supported (either all
1121	* or that specific property). The caller must handle this result.
1122	* @retval VERR_NOT_FOUND the property was not found in the module. The caller
1123	* must also normally deal with this.
1124	* @retval VERR_INVALID_FUNCTION if the function value is wrong.
1125	* @retval VERR_INVALID_PARAMETER if the buffer size is wrong.
1126	* @retval VERR_BUFFER_OVERFLOW if the function doesn't have a fixed size
1127	* buffer and the buffer isn't big enough. Use RTLdrQueryPropEx.
1128	* @retval VERR_INVALID_HANDLE if the handle is invalid.
1129	*
1130	* @param hLdrMod The module handle.
1131	* @param enmProp The property to query.
1132	* @param pvBuf Pointer to the input / output buffer. In most cases
1133	* it's only used for returning data.
1134	* @param cbBuf The size of the buffer.
1135	*/
1136	RTDECL(int) RTLdrQueryProp(RTLDRMOD hLdrMod, RTLDRPROP enmProp, void *pvBuf, size_t cbBuf);
1137
1138	/**
1139	* Generic method for querying image properties, extended version.
1140	*
1141	* @returns IPRT status code.
1142	* @retval VERR_NOT_SUPPORTED if the property query isn't supported (either all
1143	* or that specific property). The caller must handle this result.
1144	* @retval VERR_NOT_FOUND the property was not found in the module. The caller
1145	* must also normally deal with this.
1146	* @retval VERR_INVALID_FUNCTION if the function value is wrong.
1147	* @retval VERR_INVALID_PARAMETER if the fixed buffer size is wrong. Correct
1148	* size in @a *pcbRet.
1149	* @retval VERR_BUFFER_OVERFLOW if the function doesn't have a fixed size
1150	* buffer and the buffer isn't big enough. Correct size in @a *pcbRet.
1151	* @retval VERR_INVALID_HANDLE if the handle is invalid.
1152	*
1153	* @param hLdrMod The module handle.
1154	* @param enmProp The property to query.
1155	* @param pvBits Optional pointer to bits returned by
1156	* RTLdrGetBits(). This can be utilized by some module
1157	* interpreters to reduce memory consumption and file
1158	* access.
1159	* @param pvBuf Pointer to the input / output buffer. In most cases
1160	* it's only used for returning data.
1161	* @param cbBuf The size of the buffer.
1162	* @param pcbRet Where to return the amount of data returned. On
1163	* buffer size errors, this is set to the correct size.
1164	* Optional.
1165	*/
1166	RTDECL(int) RTLdrQueryPropEx(RTLDRMOD hLdrMod, RTLDRPROP enmProp, void pvBits, void pvBuf, size_t cbBuf, size_t *pcbRet);
1167
1168
1169	/**
1170	* Signature type, see FNRTLDRVALIDATESIGNEDDATA.
1171	*/
1172	typedef enum RTLDRSIGNATURETYPE
1173	{
1174	/** Invalid value. */
1175	RTLDRSIGNATURETYPE_INVALID = 0,
1176	/** A RTPKCS7CONTENTINFO structure w/ RTPKCS7SIGNEDDATA inside.
1177	* It's parsed, so the whole binary ASN.1 representation can be found by
1178	* using RTASN1CORE_GET_RAW_ASN1_PTR() and RTASN1CORE_GET_RAW_ASN1_SIZE(). */
1179	RTLDRSIGNATURETYPE_PKCS7_SIGNED_DATA,
1180	/** End of valid values. */
1181	RTLDRSIGNATURETYPE_END,
1182	/** Make sure the size is 32-bit. */
1183	RTLDRSIGNATURETYPE_32BIT_HACK = 0x7fffffff
1184	} RTLDRSIGNATURETYPE;
1185
1186	/**
1187	* Callback used by RTLdrVerifySignature to verify the signature and associated
1188	* certificates.
1189	*
1190	* @returns IPRT status code.
1191	* @param hLdrMod The module handle.
1192	* @param enmSignature The signature format.
1193	* @param pvSignature The signature data. Format given by @a enmSignature.
1194	* @param cbSignature The size of the buffer @a pvSignature points to.
1195	* @param pErrInfo Pointer to an error info buffer, optional.
1196	* @param pvUser User argument.
1197	*
1198	*/
1199	typedef DECLCALLBACK(int) FNRTLDRVALIDATESIGNEDDATA(RTLDRMOD hLdrMod, RTLDRSIGNATURETYPE enmSignature, void const *pvSignature, size_t cbSignature,
1200	PRTERRINFO pErrInfo, void *pvUser);
1201	/** Pointer to a signature verification callback. */
1202	typedef FNRTLDRVALIDATESIGNEDDATA *PFNRTLDRVALIDATESIGNEDDATA;
1203
1204	/**
1205	* Verify the image signature.
1206	*
1207	* This may permform additional integrity checks on the image structures that
1208	* was not done when opening the image.
1209	*
1210	* @returns IPRT status code.
1211	* @retval VERR_LDRVI_NOT_SIGNED if not signed.
1212	*
1213	* @param hLdrMod The module handle.
1214	* @param pfnCallback Callback that does the signature and certificate
1215	* verficiation.
1216	* @param pvUser User argument for the callback.
1217	* @param pErrInfo Pointer to an error info buffer. Optional.
1218	*/
1219	RTDECL(int) RTLdrVerifySignature(RTLDRMOD hLdrMod, PFNRTLDRVALIDATESIGNEDDATA pfnCallback, void *pvUser, PRTERRINFO pErrInfo);
1220
1221	/**
1222	* Calculate the image hash according the image signing rules.
1223	*
1224	* @returns IPRT status code.
1225	* @param hLdrMod The module handle.
1226	* @param enmDigest Which kind of digest.
1227	* @param pszDigest Where to store the image digest.
1228	* @param cbDigest Size of the buffer @a pszDigest points at.
1229	*/
1230	RTDECL(int) RTLdrHashImage(RTLDRMOD hLdrMod, RTDIGESTTYPE enmDigest, char *pszDigest, size_t cbDigest);
1231
1232	/**
1233	* Try use unwind information to unwind one frame.
1234	*
1235	* @returns IPRT status code. Last informational status from stack reader callback.
1236	* @retval VERR_DBG_NO_UNWIND_INFO if the module contains no unwind information.
1237	* @retval VERR_DBG_UNWIND_INFO_NOT_FOUND if no unwind information was found
1238	* for the location given by iSeg:off.
1239	*
1240	* @param hLdrMod The module handle.
1241	* @param pvBits Optional pointer to bits returned by
1242	* RTLdrGetBits(). This can be utilized by some module
1243	* interpreters to reduce memory consumption and file
1244	* access.
1245	* @param iSeg The segment number of the program counter. UINT32_MAX if RVA.
1246	* @param off The offset into @a iSeg. Together with @a iSeg
1247	* this corresponds to the RTDBGUNWINDSTATE::uPc
1248	* value pointed to by @a pState.
1249	* @param pState The unwind state to work.
1250	*
1251	* @sa RTDbgModUnwindFrame
1252	*/
1253	RTDECL(int) RTLdrUnwindFrame(RTLDRMOD hLdrMod, void const *pvBits, uint32_t iSeg, RTLDRADDR off, PRTDBGUNWINDSTATE pState);
1254
1255	RT_C_DECLS_END
1256
1257	/** @} */
1258
1259	#endif
1260

Note: See TracBrowser for help on using the repository browser.

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

Download in other formats: