ldr.h@ 99049

Last change on this file since 99049 was 98103, checked in by vboxsync, 23 months ago
Copyright year updates by scm.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 50.7 KB

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

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

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

Download in other formats: