ldr.h@ 86716

Last change on this file since 86716 was 86552, checked in by vboxsync, 4 years ago
SUPHardNt,IPRT: If there are nested signatures (i.e. more than one signature), don't get grumpy if there are time or cert path issues with some of them, as long as one or more checks out perfectly. (Mind, all the signature data must check out, it's just the cert path or signing time we're relaxing here.) [doxyfix] ticketref:19743 bugref:3103
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 49.5 KB

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

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

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

Download in other formats: