ldr.h@ 95929

Last change on this file since 95929 was 95612, checked in by vboxsync, 2 years ago
IPRT/ldr: Changed RTLdrHashImage to return the hash rather than the digest string. bugref:8691
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 50.4 KB

Line
1	/** @file
2	* IPRT - Loader.
3	*/
4
5	/*
6	* Copyright (C) 2006-2022 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	/** Query the number of pages that needs hashing.
1108	* This is for RTLDRPROP_SHA1_PAGE_HASHES and RTLDRPROP_SHA256_PAGE_HASHES
1109	* buffer size calculations. */
1110	RTLDRPROP_HASHABLE_PAGES,
1111	/** Query the SHA-1 page hashes.
1112	* Returns an array with entries made of a 32-bit file offset and a SHA-1
1113	* digest. Use RTLDRPROP_HASHABLE_PAGES to calculate the buffer size. */
1114	RTLDRPROP_SHA1_PAGE_HASHES,
1115	/** Query the SHA-256 page hashes.
1116	* Returns an array with entries made of a 32-bit file offset and a SHA-256
1117	* digest. Use RTLDRPROP_HASHABLE_PAGES to calculate the buffer size. */
1118	RTLDRPROP_SHA256_PAGE_HASHES,
1119
1120	/** Query whether code signature checks are enabled. */
1121	RTLDRPROP_SIGNATURE_CHECKS_ENFORCED,
1122
1123	/** Number of import or needed modules. */
1124	RTLDRPROP_IMPORT_COUNT,
1125	/** Import module by index (32-bit) stored in the buffer. */
1126	RTLDRPROP_IMPORT_MODULE,
1127	/** The file offset of the main executable header.
1128	* This is mainly for PE, NE and LX headers, but also Mach-O FAT. */
1129	RTLDRPROP_FILE_OFF_HEADER,
1130	/** The internal module name.
1131	* This is the SONAME for ELF, export table name for PE, and zero'th resident
1132	* name table entry for LX.
1133	* Returns zero terminated string. */
1134	RTLDRPROP_INTERNAL_NAME,
1135	/** The raw unwind table if available.
1136	* For PE this means IMAGE_DIRECTORY_ENTRY_EXCEPTION content, for AMD64 this
1137	* is the lookup table (IMAGE_RUNTIME_FUNCTION_ENTRY).
1138	* Not implemented any others yet. */
1139	RTLDRPROP_UNWIND_TABLE,
1140	/** Read unwind info at given RVA and up to buffer size. The RVA is stored
1141	* as uint32_t in the buffer when making the call.
1142	* This is only implemented for PE. */
1143	RTLDRPROP_UNWIND_INFO,
1144	/** The image build-id (ELF/GNU).
1145	* Returns usually a SHA1 checksum in the buffer. */
1146	RTLDRPROP_BUILDID,
1147
1148	/** End of valid properties. */
1149	RTLDRPROP_END,
1150	/** Blow the type up to 32 bits. */
1151	RTLDRPROP_32BIT_HACK = 0x7fffffff
1152	} RTLDRPROP;
1153
1154	/**
1155	* Generic method for querying image properties.
1156	*
1157	* @returns IPRT status code.
1158	* @retval VERR_NOT_SUPPORTED if the property query isn't supported (either all
1159	* or that specific property). The caller must handle this result.
1160	* @retval VERR_NOT_FOUND the property was not found in the module. The caller
1161	* must also normally deal with this.
1162	* @retval VERR_INVALID_FUNCTION if the function value is wrong.
1163	* @retval VERR_INVALID_PARAMETER if the buffer size is wrong.
1164	* @retval VERR_BUFFER_OVERFLOW if the function doesn't have a fixed size
1165	* buffer and the buffer isn't big enough. Use RTLdrQueryPropEx.
1166	* @retval VERR_INVALID_HANDLE if the handle is invalid.
1167	*
1168	* @param hLdrMod The module handle.
1169	* @param enmProp The property to query.
1170	* @param pvBuf Pointer to the input / output buffer. In most cases
1171	* it's only used for returning data.
1172	* @param cbBuf The size of the buffer.
1173	*/
1174	RTDECL(int) RTLdrQueryProp(RTLDRMOD hLdrMod, RTLDRPROP enmProp, void *pvBuf, size_t cbBuf);
1175
1176	/**
1177	* Generic method for querying image properties, extended version.
1178	*
1179	* @returns IPRT status code.
1180	* @retval VERR_NOT_SUPPORTED if the property query isn't supported (either all
1181	* or that specific property). The caller must handle this result.
1182	* @retval VERR_NOT_FOUND the property was not found in the module. The caller
1183	* must also normally deal with this.
1184	* @retval VERR_INVALID_FUNCTION if the function value is wrong.
1185	* @retval VERR_INVALID_PARAMETER if the fixed buffer size is wrong. Correct
1186	* size in @a *pcbRet.
1187	* @retval VERR_BUFFER_OVERFLOW if the function doesn't have a fixed size
1188	* buffer and the buffer isn't big enough. Correct size in @a *pcbRet.
1189	* @retval VERR_INVALID_HANDLE if the handle is invalid.
1190	*
1191	* @param hLdrMod The module handle.
1192	* @param enmProp The property to query.
1193	* @param pvBits Optional pointer to bits returned by
1194	* RTLdrGetBits(). This can be utilized by some module
1195	* interpreters to reduce memory consumption and file
1196	* access.
1197	* @param pvBuf Pointer to the input / output buffer. In most cases
1198	* it's only used for returning data.
1199	* @param cbBuf The size of the buffer.
1200	* @param pcbRet Where to return the amount of data returned. On
1201	* buffer size errors, this is set to the correct size.
1202	* Optional.
1203	*/
1204	RTDECL(int) RTLdrQueryPropEx(RTLDRMOD hLdrMod, RTLDRPROP enmProp, void pvBits, void pvBuf, size_t cbBuf, size_t *pcbRet);
1205
1206
1207	/**
1208	* Signature type, see FNRTLDRVALIDATESIGNEDDATA.
1209	*/
1210	typedef enum RTLDRSIGNATURETYPE
1211	{
1212	/** Invalid value. */
1213	RTLDRSIGNATURETYPE_INVALID = 0,
1214	/** A RTPKCS7CONTENTINFO structure w/ RTPKCS7SIGNEDDATA inside.
1215	* It's parsed, so the whole binary ASN.1 representation can be found by
1216	* using RTASN1CORE_GET_RAW_ASN1_PTR() and RTASN1CORE_GET_RAW_ASN1_SIZE(). */
1217	RTLDRSIGNATURETYPE_PKCS7_SIGNED_DATA,
1218	/** End of valid values. */
1219	RTLDRSIGNATURETYPE_END,
1220	/** Make sure the size is 32-bit. */
1221	RTLDRSIGNATURETYPE_32BIT_HACK = 0x7fffffff
1222	} RTLDRSIGNATURETYPE;
1223
1224	/**
1225	* Signature information provided by FNRTLDRVALIDATESIGNEDDATA.
1226	*/
1227	typedef struct RTLDRSIGNATUREINFO
1228	{
1229	/** The signature number (0-based). */
1230	uint16_t iSignature;
1231	/** The total number of signatures. */
1232	uint16_t cSignatures;
1233	/** Sginature format type. */
1234	RTLDRSIGNATURETYPE enmType;
1235	/** The signature data (formatted according to enmType). */
1236	void const *pvSignature;
1237	/** The size of the buffer pvSignature points to. */
1238	size_t cbSignature;
1239	/** Pointer to the signed data, if external.
1240	* NULL if the data is internal to the signature structure. */
1241	void const *pvExternalData;
1242	/** Size of the signed data, if external.
1243	* 0 if internal to the signature structure. */
1244	size_t cbExternalData;
1245	} RTLDRSIGNATUREINFO;
1246	/** Pointer to a signature structure. */
1247	typedef RTLDRSIGNATUREINFO *PRTLDRSIGNATUREINFO;
1248	/** Pointer to a const signature structure. */
1249	typedef RTLDRSIGNATUREINFO const *PCRTLDRSIGNATUREINFO;
1250
1251	/**
1252	* Callback used by RTLdrVerifySignature to verify the signature and associated
1253	* certificates.
1254	*
1255	* This is called multiple times when the executable contains more than one
1256	* signature (PE only at the moment). The RTLDRSIGNATUREINFO::cSignatures gives
1257	* the total number of signatures (and thereby callbacks) and
1258	* RTLDRSIGNATUREINFO::iSignature indicates the current one.
1259	*
1260	* @returns IPRT status code. A status code other than VINF_SUCCESS will
1261	* prevent callbacks the remaining signatures (if any).
1262	* @param hLdrMod The module handle.
1263	* @param pInfo Signature information.
1264	* @param pErrInfo Pointer to an error info buffer, optional.
1265	* @param pvUser User argument.
1266	*/
1267	typedef DECLCALLBACKTYPE(int, FNRTLDRVALIDATESIGNEDDATA,(RTLDRMOD hLdrMod, PCRTLDRSIGNATUREINFO pInfo,
1268	PRTERRINFO pErrInfo, void *pvUser));
1269	/** Pointer to a signature verification callback. */
1270	typedef FNRTLDRVALIDATESIGNEDDATA *PFNRTLDRVALIDATESIGNEDDATA;
1271
1272	/**
1273	* Verify the image signature.
1274	*
1275	* This may permform additional integrity checks on the image structures that
1276	* was not done when opening the image.
1277	*
1278	* @returns IPRT status code.
1279	* @retval VERR_LDRVI_NOT_SIGNED if not signed.
1280	*
1281	* @param hLdrMod The module handle.
1282	* @param pfnCallback Callback that does the signature and certificate
1283	* verficiation.
1284	* @param pvUser User argument for the callback.
1285	* @param pErrInfo Pointer to an error info buffer. Optional.
1286	*/
1287	RTDECL(int) RTLdrVerifySignature(RTLDRMOD hLdrMod, PFNRTLDRVALIDATESIGNEDDATA pfnCallback, void *pvUser, PRTERRINFO pErrInfo);
1288
1289	/**
1290	* Calculate the image hash according the image signing rules.
1291	*
1292	* @returns IPRT status code.
1293	* @param hLdrMod The module handle.
1294	* @param enmDigest Which kind of digest.
1295	* @param pabHash Where to store the image hash.
1296	* @param cbHash Size of the buffer @a pabHash points at. The
1297	* required and returned size can be derived from the
1298	* digest type (@a enmDigest).
1299	*/
1300	RTDECL(int) RTLdrHashImage(RTLDRMOD hLdrMod, RTDIGESTTYPE enmDigest, uint8_t *pabHash, size_t cbHash);
1301
1302	/**
1303	* Try use unwind information to unwind one frame.
1304	*
1305	* @returns IPRT status code. Last informational status from stack reader callback.
1306	* @retval VERR_DBG_NO_UNWIND_INFO if the module contains no unwind information.
1307	* @retval VERR_DBG_UNWIND_INFO_NOT_FOUND if no unwind information was found
1308	* for the location given by iSeg:off.
1309	*
1310	* @param hLdrMod The module handle.
1311	* @param pvBits Optional pointer to bits returned by
1312	* RTLdrGetBits(). This can be utilized by some module
1313	* interpreters to reduce memory consumption and file
1314	* access.
1315	* @param iSeg The segment number of the program counter. UINT32_MAX if RVA.
1316	* @param off The offset into @a iSeg. Together with @a iSeg
1317	* this corresponds to the RTDBGUNWINDSTATE::uPc
1318	* value pointed to by @a pState.
1319	* @param pState The unwind state to work.
1320	*
1321	* @sa RTDbgModUnwindFrame
1322	*/
1323	RTDECL(int) RTLdrUnwindFrame(RTLDRMOD hLdrMod, void const *pvBits, uint32_t iSeg, RTLDRADDR off, PRTDBGUNWINDSTATE pState);
1324
1325	RT_C_DECLS_END
1326
1327	/** @} */
1328
1329	#endif /* !IPRT_INCLUDED_ldr_h */
1330

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

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

Download in other formats: