ldr.h@ 78286

Last change on this file since 78286 was 77971, checked in by vboxsync, 6 years ago
Runtime/ldr: Make RTLDRREADER::pfnSize return an unsigned 64bit value instead of a signed one for the raw image size and adapt all users. This avoids signed/unsigned confusions when comparing those value with others (bugref:9188)
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 46.3 KB

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

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

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

Download in other formats: