ldr.h@ 49907

Last change on this file since 49907 was 49044, checked in by vboxsync, 11 years ago
Darwin guest OS digger hacking in progress. Adding symbol cache util to iprt and started on the Mach-O code that'll make use of it (RTDbgModCreateFromMachOImage++). Updates kStuff from 53 to 55 for UUID query and 64-bit kext loading.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 30.4 KB

Line
1	/** @file
2	* IPRT - Loader.
3	*/
4
5	/*
6	* Copyright (C) 2006-2011 Oracle Corporation
7	*
8	* This file is part of VirtualBox Open Source Edition (OSE), as
9	* available from http://www.virtualbox.org. This file is free software;
10	* you can redistribute it and/or modify it under the terms of the GNU
11	* General Public License (GPL) as published by the Free Software
12	* Foundation, in version 2 as it comes in the "COPYING" file of the
13	* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14	* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15	*
16	* The contents of this file may alternatively be used under the terms
17	* of the Common Development and Distribution License Version 1.0
18	* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19	* VirtualBox OSE distribution, in which case the provisions of the
20	* CDDL are applicable instead of those of the GPL.
21	*
22	* You may elect to license modified versions of this file under the
23	* terms and conditions of either the GPL or the CDDL or both.
24	*/
25
26	#ifndef ___iprt_ldr_h
27	#define ___iprt_ldr_h
28
29	#include <iprt/cdefs.h>
30	#include <iprt/types.h>
31
32
33	/** @defgroup grp_ldr RTLdr - Loader
34	* @ingroup grp_rt
35	* @{
36	*/
37
38
39	RT_C_DECLS_BEGIN
40
41	/** Loader address (unsigned integer). */
42	typedef RTUINTPTR RTLDRADDR;
43	/** Pointer to a loader address. */
44	typedef RTLDRADDR *PRTLDRADDR;
45	/** Pointer to a const loader address. */
46	typedef RTLDRADDR const *PCRTLDRADDR;
47	/** The max loader address value. */
48	#define RTLDRADDR_MAX RTUINTPTR_MAX
49	/** NIL loader address value. */
50	#define NIL_RTLDRADDR RTLDRADDR_MAX
51
52
53	/**
54	* Loader module format.
55	*/
56	typedef enum RTLDRFMT
57	{
58	/** The usual invalid 0 format. */
59	RTLDRFMT_INVALID = 0,
60	/** The native OS loader. */
61	RTLDRFMT_NATIVE,
62	/** The AOUT loader. */
63	RTLDRFMT_AOUT,
64	/** The ELF loader. */
65	RTLDRFMT_ELF,
66	/** The LX loader. */
67	RTLDRFMT_LX,
68	/** The Mach-O loader. */
69	RTLDRFMT_MACHO,
70	/** The PE loader. */
71	RTLDRFMT_PE,
72	/** The end of the valid format values (exclusive). */
73	RTLDRFMT_END,
74	/** Hack to blow the type up to 32-bit. */
75	RTLDRFMT_32BIT_HACK = 0x7fffffff
76	} RTLDRFMT;
77
78
79	/**
80	* Loader module type.
81	*/
82	typedef enum RTLDRTYPE
83	{
84	/** The usual invalid 0 type. */
85	RTLDRTYPE_INVALID = 0,
86	/** Object file. */
87	RTLDRTYPE_OBJECT,
88	/** Executable module, fixed load address. */
89	RTLDRTYPE_EXECUTABLE_FIXED,
90	/** Executable module, relocatable, non-fixed load address. */
91	RTLDRTYPE_EXECUTABLE_RELOCATABLE,
92	/** Executable module, position independent code, non-fixed load address. */
93	RTLDRTYPE_EXECUTABLE_PIC,
94	/** Shared library, fixed load address.
95	* Typically a system library. */
96	RTLDRTYPE_SHARED_LIBRARY_FIXED,
97	/** Shared library, relocatable, non-fixed load address. */
98	RTLDRTYPE_SHARED_LIBRARY_RELOCATABLE,
99	/** Shared library, position independent code, non-fixed load address. */
100	RTLDRTYPE_SHARED_LIBRARY_PIC,
101	/** DLL that contains no code or data only imports and exports. (Chiefly OS/2.) */
102	RTLDRTYPE_FORWARDER_DLL,
103	/** Core or dump. */
104	RTLDRTYPE_CORE,
105	/** Debug module (debug info with empty code & data segments). */
106	RTLDRTYPE_DEBUG_INFO,
107	/** The end of the valid types values (exclusive). */
108	RTLDRTYPE_END,
109	/** Hack to blow the type up to 32-bit. */
110	RTLDRTYPE_32BIT_HACK = 0x7fffffff
111	} RTLDRTYPE;
112
113
114	/**
115	* Loader endian indicator.
116	*/
117	typedef enum RTLDRENDIAN
118	{
119	/** The usual invalid endian. */
120	RTLDRENDIAN_INVALID,
121	/** Little endian. */
122	RTLDRENDIAN_LITTLE,
123	/** Bit endian. */
124	RTLDRENDIAN_BIG,
125	/** Endianness doesn't have a meaning in the context. */
126	RTLDRENDIAN_NA,
127	/** The end of the valid endian values (exclusive). */
128	RTLDRENDIAN_END,
129	/** Hack to blow the type up to 32-bit. */
130	RTLDRENDIAN_32BIT_HACK = 0x7fffffff
131	} RTLDRENDIAN;
132
133
134	/**
135	* Gets the default file suffix for DLL/SO/DYLIB/whatever.
136	*
137	* @returns The stuff (readonly).
138	*/
139	RTDECL(const char *) RTLdrGetSuff(void);
140
141	/**
142	* Checks if a library is loadable or not.
143	*
144	* This may attempt load and unload the library.
145	*
146	* @returns true/false accordingly.
147	* @param pszFilename Image filename.
148	*/
149	RTDECL(bool) RTLdrIsLoadable(const char *pszFilename);
150
151	/**
152	* Loads a dynamic load library (/shared object) image file using native
153	* OS facilities.
154	*
155	* The filename will be appended the default DLL/SO extension of
156	* the platform if it have been omitted. This means that it's not
157	* possible to load DLLs/SOs with no extension using this interface,
158	* but that's not a bad tradeoff.
159	*
160	* If no path is specified in the filename, the OS will usually search it's library
161	* path to find the image file.
162	*
163	* @returns iprt status code.
164	* @param pszFilename Image filename.
165	* @param phLdrMod Where to store the handle to the loader module.
166	*/
167	RTDECL(int) RTLdrLoad(const char *pszFilename, PRTLDRMOD phLdrMod);
168
169	/**
170	* Loads a dynamic load library (/shared object) image file using native
171	* OS facilities.
172	*
173	* The filename will be appended the default DLL/SO extension of
174	* the platform if it have been omitted. This means that it's not
175	* possible to load DLLs/SOs with no extension using this interface,
176	* but that's not a bad tradeoff.
177	*
178	* If no path is specified in the filename, the OS will usually search it's library
179	* path to find the image file.
180	*
181	* @returns iprt status code.
182	* @param pszFilename Image filename.
183	* @param phLdrMod Where to store the handle to the loader module.
184	* @param fFlags See RTLDRLOAD_FLAGS_XXX.
185	* @param pErrInfo Where to return extended error information. Optional.
186	*/
187	RTDECL(int) RTLdrLoadEx(const char *pszFilename, PRTLDRMOD phLdrMod, uint32_t fFlags, PRTERRINFO pErrInfo);
188
189	/** @defgroup RTLDRLOAD_FLAGS_XXX RTLdrLoadEx flags.
190	* @{ */
191	/** Symbols defined in this library are not made available to resolve
192	* references in subsequently loaded libraries (default). */
193	#define RTLDRLOAD_FLAGS_LOCAL UINT32_C(0)
194	/** Symbols defined in this library will be made available for symbol
195	* resolution of subsequently loaded libraries. */
196	#define RTLDRLOAD_FLAGS_GLOBAL RT_BIT_32(0)
197	/** Do not unload the library upon RTLdrClose. (For system libs.) */
198	#define RTLDRLOAD_FLAGS_NO_UNLOAD RT_BIT_32(1)
199	/** The mask of valid flag bits. */
200	#define RTLDRLOAD_FLAGS_VALID_MASK UINT32_C(0x00000003)
201	/** @} */
202
203	/**
204	* Loads a dynamic load library (/shared object) image file residing in one of
205	* the default system library locations.
206	*
207	* Only the system library locations are searched. No suffix is required.
208	*
209	* @returns iprt status code.
210	* @param pszFilename Image filename. No path.
211	* @param fNoUnload Do not unload the library when RTLdrClose is called.
212	* @param phLdrMod Where to store the handle to the loaded module.
213	*/
214	RTDECL(int) RTLdrLoadSystem(const char *pszFilename, bool fNoUnload, PRTLDRMOD phLdrMod);
215
216	/**
217	* Combines RTLdrLoadSystem and RTLdrGetSymbol, with fNoUnload set to true.
218	*
219	* @returns The symbol value, NULL on failure. (If you care for a less boolean
220	* status, go thru the necessary API calls yourself.)
221	* @param pszFilename Image filename. No path.
222	* @param pszSymbol Symbol name.
223	*/
224	RTDECL(void ) RTLdrGetSystemSymbol(const char pszFilename, const char *pszSymbol);
225
226	/**
227	* Loads a dynamic load library (/shared object) image file residing in the
228	* RTPathAppPrivateArch() directory.
229	*
230	* Suffix is not required.
231	*
232	* @returns iprt status code.
233	* @param pszFilename Image filename. No path.
234	* @param phLdrMod Where to store the handle to the loaded module.
235	*/
236	RTDECL(int) RTLdrLoadAppPriv(const char *pszFilename, PRTLDRMOD phLdrMod);
237
238	/**
239	* Gets the native module handle for a module loaded by RTLdrLoad, RTLdrLoadEx,
240	* RTLdrLoadSystem, or RTLdrLoadAppPriv.
241	*
242	* @returns Native handle on success, ~(uintptr_t)0 on failure.
243	* @param hLdrMod The loader module handle.
244	*/
245	RTDECL(uintptr_t) RTLdrGetNativeHandle(RTLDRMOD hLdrMod);
246
247
248	/**
249	* Image architecuture specifier for RTLdrOpenEx.
250	*/
251	typedef enum RTLDRARCH
252	{
253	RTLDRARCH_INVALID = 0,
254	/** Whatever. */
255	RTLDRARCH_WHATEVER,
256	/** The host architecture. */
257	RTLDRARCH_HOST,
258	/** 32-bit x86. */
259	RTLDRARCH_X86_32,
260	/** AMD64 (64-bit x86 if you like). */
261	RTLDRARCH_AMD64,
262	/** End of the valid values. */
263	RTLDRARCH_END,
264	/** Make sure the type is a full 32-bit. */
265	RTLDRARCH_32BIT_HACK = 0x7fffffff
266	} RTLDRARCH;
267	/** Pointer to a RTLDRARCH. */
268	typedef RTLDRARCH *PRTLDRARCH;
269
270	/** @name RTLDR_O_XXX - RTLdrOpen flags.
271	* @{ */
272	/** Open for debugging or introspection reasons.
273	* This will skip a few of the stricter validations when loading images. */
274	#define RTLDR_O_FOR_DEBUG RT_BIT_32(0)
275	/** Mask of valid flags. */
276	#define RTLDR_O_VALID_MASK UINT32_C(0x00000001)
277	/** @} */
278
279	/**
280	* Open a binary image file, extended version.
281	*
282	* @returns iprt status code.
283	* @param pszFilename Image filename.
284	* @param fFlags Valid RTLDR_O_XXX combination.
285	* @param enmArch CPU architecture specifier for the image to be loaded.
286	* @param phLdrMod Where to store the handle to the loader module.
287	*/
288	RTDECL(int) RTLdrOpen(const char *pszFilename, uint32_t fFlags, RTLDRARCH enmArch, PRTLDRMOD phLdrMod);
289
290	/**
291	* Opens a binary image file using kLdr.
292	*
293	* @returns iprt status code.
294	* @param pszFilename Image filename.
295	* @param phLdrMod Where to store the handle to the loaded module.
296	* @param fFlags Valid RTLDR_O_XXX combination.
297	* @param enmArch CPU architecture specifier for the image to be loaded.
298	* @remark Primarily for testing the loader.
299	*/
300	RTDECL(int) RTLdrOpenkLdr(const char *pszFilename, uint32_t fFlags, RTLDRARCH enmArch, PRTLDRMOD phLdrMod);
301
302
303	/**
304	* Called to read @a cb bytes at @a off into @a pvBuf.
305	*
306	* @returns IPRT status code
307	* @param pvBuf The output buffer.
308	* @param cb The number of bytes to read.
309	* @param off Where to start reading.
310	* @param pvUser The user parameter.
311	*/
312	typedef DECLCALLBACK(int) FNRTLDRRDRMEMREAD(void pvBuf, size_t cb, size_t off, void pvUser);
313	/** Pointer to a RTLdrOpenInMemory reader callback. */
314	typedef FNRTLDRRDRMEMREAD *PFNRTLDRRDRMEMREAD;
315
316	/**
317	* Called to when the module is unloaded (or done loading) to release resources
318	* associated with it (@a pvUser).
319	*
320	* @returns IPRT status code
321	* @param pvUser The user parameter.
322	*/
323	typedef DECLCALLBACK(void) FNRTLDRRDRMEMDTOR(void *pvUser);
324	/** Pointer to a RTLdrOpenInMemory destructor callback. */
325	typedef FNRTLDRRDRMEMDTOR *PFNRTLDRRDRMEMDTOR;
326
327	/**
328	* Open a in-memory image or an image with a custom reader callback.
329	*
330	* @returns IPRT status code.
331	* @param pszName The image name.
332	* @param fFlags Valid RTLDR_O_XXX combination.
333	* @param enmArch CPU architecture specifier for the image to be loaded.
334	* @param cbImage The size of the image (fake file).
335	* @param pfnRead The read function. If NULL is passed in, a default
336	* reader function is provided that assumes @a pvUser
337	* points to the raw image bits, at least @a cbImage of
338	* valid memory.
339	* @param pfnDtor The destructor function. If NULL is passed, a default
340	* destructor will be provided that passes @a pvUser to
341	* RTMemFree.
342	* @param pvUser The user argument or, if any of the callbacks are NULL,
343	* a pointer to a memory block.
344	* @param phLdrMod Where to return the module handle.
345	*
346	* @remarks With the exception of invalid @a pfnDtor and/or @a pvUser
347	* parameters, the pfnDtor methods (or the default one if NULL) will
348	* always be invoked. The destruction of pvUser is entirely in the
349	* hands of this method once it's called.
350	*/
351	RTDECL(int) RTLdrOpenInMemory(const char *pszName, uint32_t fFlags, RTLDRARCH enmArch, size_t cbImage,
352	PFNRTLDRRDRMEMREAD pfnRead, PFNRTLDRRDRMEMDTOR pfnDtor, void *pvUser,
353	PRTLDRMOD phLdrMod);
354
355	/**
356	* Closes a loader module handle.
357	*
358	* The handle can be obtained using any of the RTLdrLoad(), RTLdrOpen()
359	* and RTLdrOpenInMemory() functions.
360	*
361	* @returns iprt status code.
362	* @param hLdrMod The loader module handle.
363	*/
364	RTDECL(int) RTLdrClose(RTLDRMOD hLdrMod);
365
366	/**
367	* Gets the address of a named exported symbol.
368	*
369	* @returns iprt status code.
370	* @param hLdrMod The loader module handle.
371	* @param pszSymbol Symbol name.
372	* @param ppvValue Where to store the symbol value. Note that this is restricted to the
373	* pointer size used on the host!
374	*/
375	RTDECL(int) RTLdrGetSymbol(RTLDRMOD hLdrMod, const char pszSymbol, void *ppvValue);
376
377	/**
378	* Gets the address of a named exported symbol.
379	*
380	* This function differs from the plain one in that it can deal with
381	* both GC and HC address sizes, and that it can calculate the symbol
382	* value relative to any given base address.
383	*
384	* @returns iprt status code.
385	* @param hLdrMod The loader module handle.
386	* @param pvBits Optional pointer to the loaded image.
387	* Set this to NULL if no RTLdrGetBits() processed image bits are available.
388	* Not supported for RTLdrLoad() images.
389	* @param BaseAddress Image load address.
390	* Not supported for RTLdrLoad() images.
391	* @param pszSymbol Symbol name.
392	* @param pValue Where to store the symbol value.
393	*/
394	RTDECL(int) RTLdrGetSymbolEx(RTLDRMOD hLdrMod, const void pvBits, RTLDRADDR BaseAddress, const char pszSymbol,
395	PRTLDRADDR pValue);
396
397
398	/**
399	* Gets the address of a named exported function.
400	*
401	* Same as RTLdrGetSymbol, but skips the status code and pointer to return
402	* variable stuff.
403	*
404	* @returns Pointer to the function if found, NULL if not.
405	* @param hLdrMod The loader module handle.
406	* @param pszSymbol Function name.
407	*/
408	RTDECL(PFNRT) RTLdrGetFunction(RTLDRMOD hLdrMod, const char *pszSymbol);
409
410	/**
411	* Gets the size of the loaded image.
412	*
413	* This is not necessarily available for images that has been loaded using
414	* RTLdrLoad().
415	*
416	* @returns image size (in bytes).
417	* @returns ~(size_t)0 on if not available.
418	* @param hLdrMod Handle to the loader module.
419	*/
420	RTDECL(size_t) RTLdrSize(RTLDRMOD hLdrMod);
421
422	/**
423	* Resolve an external symbol during RTLdrGetBits().
424	*
425	* @returns iprt status code.
426	* @param hLdrMod The loader module handle.
427	* @param pszModule Module name.
428	* @param pszSymbol Symbol name, NULL if uSymbol should be used.
429	* @param uSymbol Symbol ordinal, ~0 if pszSymbol should be used.
430	* @param pValue Where to store the symbol value (address).
431	* @param pvUser User argument.
432	*/
433	typedef DECLCALLBACK(int) RTLDRIMPORT(RTLDRMOD hLdrMod, const char pszModule, const char pszSymbol, unsigned uSymbol,
434	PRTLDRADDR pValue, void *pvUser);
435	/** Pointer to a FNRTLDRIMPORT() callback function. */
436	typedef RTLDRIMPORT *PFNRTLDRIMPORT;
437
438	/**
439	* Loads the image into a buffer provided by the user and applies fixups
440	* for the given base address.
441	*
442	* @returns iprt status code.
443	* @param hLdrMod The load module handle.
444	* @param pvBits Where to put the bits.
445	* Must be as large as RTLdrSize() suggests.
446	* @param BaseAddress The base address.
447	* @param pfnGetImport Callback function for resolving imports one by one.
448	* @param pvUser User argument for the callback.
449	* @remark Not supported for RTLdrLoad() images.
450	*/
451	RTDECL(int) RTLdrGetBits(RTLDRMOD hLdrMod, void pvBits, RTLDRADDR BaseAddress, PFNRTLDRIMPORT pfnGetImport, void pvUser);
452
453	/**
454	* Relocates bits after getting them.
455	* Useful for code which moves around a bit.
456	*
457	* @returns iprt status code.
458	* @param hLdrMod The loader module handle.
459	* @param pvBits Where the image bits are.
460	* Must have been passed to RTLdrGetBits().
461	* @param NewBaseAddress The new base address.
462	* @param OldBaseAddress The old base address.
463	* @param pfnGetImport Callback function for resolving imports one by one.
464	* @param pvUser User argument for the callback.
465	* @remark Not supported for RTLdrLoad() images.
466	*/
467	RTDECL(int) RTLdrRelocate(RTLDRMOD hLdrMod, void *pvBits, RTLDRADDR NewBaseAddress, RTLDRADDR OldBaseAddress,
468	PFNRTLDRIMPORT pfnGetImport, void *pvUser);
469
470	/**
471	* Enumeration callback function used by RTLdrEnumSymbols().
472	*
473	* @returns iprt status code. Failure will stop the enumeration.
474	* @param hLdrMod The loader module handle.
475	* @param pszSymbol Symbol name. NULL if ordinal only.
476	* @param uSymbol Symbol ordinal, ~0 if not used.
477	* @param Value Symbol value.
478	* @param pvUser The user argument specified to RTLdrEnumSymbols().
479	*/
480	typedef DECLCALLBACK(int) RTLDRENUMSYMS(RTLDRMOD hLdrMod, const char pszSymbol, unsigned uSymbol, RTLDRADDR Value, void pvUser);
481	/** Pointer to a RTLDRENUMSYMS() callback function. */
482	typedef RTLDRENUMSYMS *PFNRTLDRENUMSYMS;
483
484	/**
485	* Enumerates all symbols in a module.
486	*
487	* @returns iprt status code.
488	* @param hLdrMod The loader module handle.
489	* @param fFlags Flags indicating what to return and such.
490	* @param pvBits Optional pointer to the loaded image. (RTLDR_ENUM_SYMBOL_FLAGS_*)
491	* Set this to NULL if no RTLdrGetBits() processed image bits are available.
492	* @param BaseAddress Image load address.
493	* @param pfnCallback Callback function.
494	* @param pvUser User argument for the callback.
495	* @remark Not supported for RTLdrLoad() images.
496	*/
497	RTDECL(int) RTLdrEnumSymbols(RTLDRMOD hLdrMod, unsigned fFlags, const void pvBits, RTLDRADDR BaseAddress, PFNRTLDRENUMSYMS pfnCallback, void pvUser);
498
499	/** @name RTLdrEnumSymbols flags.
500	* @{ */
501	/** Returns ALL kinds of symbols. The default is to only return public/exported symbols. */
502	#define RTLDR_ENUM_SYMBOL_FLAGS_ALL RT_BIT(1)
503	/** Ignore forwarders (for use with RTLDR_ENUM_SYMBOL_FLAGS_ALL). */
504	#define RTLDR_ENUM_SYMBOL_FLAGS_NO_FWD RT_BIT(2)
505	/** @} */
506
507
508	/**
509	* Debug info type (as far the loader can tell).
510	*/
511	typedef enum RTLDRDBGINFOTYPE
512	{
513	/** The invalid 0 value. */
514	RTLDRDBGINFOTYPE_INVALID = 0,
515	/** Unknown debug info format. */
516	RTLDRDBGINFOTYPE_UNKNOWN,
517	/** Stabs. */
518	RTLDRDBGINFOTYPE_STABS,
519	/** Debug With Arbitrary Record Format (DWARF). */
520	RTLDRDBGINFOTYPE_DWARF,
521	/** Debug With Arbitrary Record Format (DWARF), in external file (DWO). */
522	RTLDRDBGINFOTYPE_DWARF_DWO,
523	/** Microsoft Codeview debug info. */
524	RTLDRDBGINFOTYPE_CODEVIEW,
525	/** Microsoft Codeview debug info, in external v2.0+ program database (PDB). */
526	RTLDRDBGINFOTYPE_CODEVIEW_PDB20,
527	/** Microsoft Codeview debug info, in external v7.0+ program database (PDB). */
528	RTLDRDBGINFOTYPE_CODEVIEW_PDB70,
529	/** Microsoft Codeview debug info, in external file (DBG). */
530	RTLDRDBGINFOTYPE_CODEVIEW_DBG,
531	/** Microsoft COFF debug info. */
532	RTLDRDBGINFOTYPE_COFF,
533	/** Watcom debug info. */
534	RTLDRDBGINFOTYPE_WATCOM,
535	/** IBM High Level Language debug info.. */
536	RTLDRDBGINFOTYPE_HLL,
537	/** The end of the valid debug info values (exclusive). */
538	RTLDRDBGINFOTYPE_END,
539	/** Blow the type up to 32-bits. */
540	RTLDRDBGINFOTYPE_32BIT_HACK = 0x7fffffff
541	} RTLDRDBGINFOTYPE;
542
543
544	/**
545	* Debug info details for the enumeration callback.
546	*/
547	typedef struct RTLDRDBGINFO
548	{
549	/** The kind of debug info. */
550	RTLDRDBGINFOTYPE enmType;
551	/** The debug info ordinal number / id. */
552	uint32_t iDbgInfo;
553	/** The file offset if this type has one specific location in the executable
554	* image file. This is -1 if there isn't any specific file location. */
555	RTFOFF offFile;
556	/** The link address of the debug info if it's loadable. NIL_RTLDRADDR if not
557	* loadable*/
558	RTLDRADDR LinkAddress;
559	/** The size of the debug information. -1 is used if this isn't applicable.*/
560	RTLDRADDR cb;
561	/** This is set if the debug information is found in an external file. NULL
562	* if no external file involved.
563	* @note Putting it outside the union to allow lazy callback implementation. */
564	const char *pszExtFile;
565	/** Type (enmType) specific information. */
566	union
567	{
568	/** RTLDRDBGINFOTYPE_DWARF */
569	struct
570	{
571	/** The section name. */
572	const char *pszSection;
573	} Dwarf;
574
575	/** RTLDRDBGINFOTYPE_DWARF_DWO */
576	struct
577	{
578	/** The CRC32 of the external file. */
579	uint32_t uCrc32;
580	} Dwo;
581
582	/** RTLDRDBGINFOTYPE_CODEVIEW, RTLDRDBGINFOTYPE_COFF */
583	struct
584	{
585	/** The PE image size. */
586	uint32_t cbImage;
587	/** The timestamp. */
588	uint32_t uTimestamp;
589	/** The major version from the entry. */
590	uint32_t uMajorVer;
591	/** The minor version from the entry. */
592	uint32_t uMinorVer;
593	} Cv, Coff;
594
595	/** RTLDRDBGINFOTYPE_CODEVIEW_DBG */
596	struct
597	{
598	/** The PE image size. */
599	uint32_t cbImage;
600	/** The timestamp. */
601	uint32_t uTimestamp;
602	} Dbg;
603
604	/** RTLDRDBGINFOTYPE_CODEVIEW_PDB20*/
605	struct
606	{
607	/** The PE image size. */
608	uint32_t cbImage;
609	/** The timestamp. */
610	uint32_t uTimestamp;
611	/** The PDB age. */
612	uint32_t uAge;
613	} Pdb20;
614
615	/** RTLDRDBGINFOTYPE_CODEVIEW_PDB70 */
616	struct
617	{
618	/** The PE image size. */
619	uint32_t cbImage;
620	/** The PDB age. */
621	uint32_t uAge;
622	/** The UUID. */
623	RTUUID Uuid;
624	} Pdb70;
625	} u;
626	} RTLDRDBGINFO;
627	/** Pointer to debug info details. */
628	typedef RTLDRDBGINFO *PRTLDRDBGINFO;
629	/** Pointer to read only debug info details. */
630	typedef RTLDRDBGINFO const *PCRTLDRDBGINFO;
631
632
633	/**
634	* Debug info enumerator callback.
635	*
636	* @returns VINF_SUCCESS to continue the enumeration. Any other status code
637	* will cause RTLdrEnumDbgInfo to immediately return with that status.
638	*
639	* @param hLdrMod The module handle.
640	* @param pDbgInfo Pointer to a read only structure with the details.
641	* @param pvUser The user parameter specified to RTLdrEnumDbgInfo.
642	*/
643	typedef DECLCALLBACK(int) FNRTLDRENUMDBG(RTLDRMOD hLdrMod, PCRTLDRDBGINFO pDbgInfo, void *pvUser);
644	/** Pointer to a debug info enumerator callback. */
645	typedef FNRTLDRENUMDBG *PFNRTLDRENUMDBG;
646
647	/**
648	* Enumerate the debug info contained in the executable image.
649	*
650	* @returns IPRT status code or whatever pfnCallback returns.
651	*
652	* @param hLdrMod The module handle.
653	* @param pvBits Optional pointer to bits returned by
654	* RTLdrGetBits(). This can be used by some module
655	* interpreters to reduce memory consumption.
656	* @param pfnCallback The callback function.
657	* @param pvUser The user argument.
658	*/
659	RTDECL(int) RTLdrEnumDbgInfo(RTLDRMOD hLdrMod, const void pvBits, PFNRTLDRENUMDBG pfnCallback, void pvUser);
660
661
662	/**
663	* Loader segment.
664	*/
665	typedef struct RTLDRSEG
666	{
667	/** The segment name. Always set to something. */
668	const char *pszName;
669	/** The length of the segment name. */
670	uint32_t cchName;
671	/** The flat selector to use for the segment (i.e. data/code).
672	* Primarily a way for the user to specify selectors for the LX/LE and NE interpreters. */
673	uint16_t SelFlat;
674	/** The 16-bit selector to use for the segment.
675	* Primarily a way for the user to specify selectors for the LX/LE and NE interpreters. */
676	uint16_t Sel16bit;
677	/** Segment flags. */
678	uint32_t fFlags;
679	/** The segment protection (RTMEM_PROT_XXX). */
680	uint32_t fProt;
681	/** The size of the segment. */
682	RTLDRADDR cb;
683	/** The required segment alignment.
684	* The to 0 if the segment isn't supposed to be mapped. */
685	RTLDRADDR Alignment;
686	/** The link address.
687	* Set to NIL_RTLDRADDR if the segment isn't supposed to be mapped or if
688	* the image doesn't have link addresses. */
689	RTLDRADDR LinkAddress;
690	/** File offset of the segment.
691	* Set to -1 if no file backing (like BSS). */
692	RTFOFF offFile;
693	/** Size of the file bits of the segment.
694	* Set to -1 if no file backing (like BSS). */
695	RTFOFF cbFile;
696	/** The relative virtual address when mapped.
697	* Set to NIL_RTLDRADDR if the segment isn't supposed to be mapped. */
698	RTLDRADDR RVA;
699	/** The size of the segment including the alignment gap up to the next segment when mapped.
700	* This is set to NIL_RTLDRADDR if not implemented. */
701	RTLDRADDR cbMapped;
702	} RTLDRSEG;
703	/** Pointer to a loader segment. */
704	typedef RTLDRSEG *PRTLDRSEG;
705	/** Pointer to a read only loader segment. */
706	typedef RTLDRSEG const *PCRTLDRSEG;
707
708
709	/** @name Segment flags
710	* @{ */
711	/** The segment is 16-bit. When not set the default of the target architecture is assumed. */
712	#define RTLDRSEG_FLAG_16BIT UINT32_C(1)
713	/** The segment requires a 16-bit selector alias. (OS/2) */
714	#define RTLDRSEG_FLAG_OS2_ALIAS16 UINT32_C(2)
715	/** Conforming segment (x86 weirdness). (OS/2) */
716	#define RTLDRSEG_FLAG_OS2_CONFORM UINT32_C(4)
717	/** IOPL (ring-2) segment. (OS/2) */
718	#define RTLDRSEG_FLAG_OS2_IOPL UINT32_C(8)
719	/** @} */
720
721	/**
722	* Segment enumerator callback.
723	*
724	* @returns VINF_SUCCESS to continue the enumeration. Any other status code
725	* will cause RTLdrEnumSegments to immediately return with that
726	* status.
727	*
728	* @param hLdrMod The module handle.
729	* @param pSeg The segment information.
730	* @param pvUser The user parameter specified to RTLdrEnumSegments.
731	*/
732	typedef DECLCALLBACK(int) FNRTLDRENUMSEGS(RTLDRMOD hLdrMod, PCRTLDRSEG pSeg, void *pvUser);
733	/** Pointer to a segment enumerator callback. */
734	typedef FNRTLDRENUMSEGS *PFNRTLDRENUMSEGS;
735
736	/**
737	* Enumerate the debug info contained in the executable image.
738	*
739	* @returns IPRT status code or whatever pfnCallback returns.
740	*
741	* @param hLdrMod The module handle.
742	* @param pfnCallback The callback function.
743	* @param pvUser The user argument.
744	*/
745	RTDECL(int) RTLdrEnumSegments(RTLDRMOD hLdrMod, PFNRTLDRENUMSEGS pfnCallback, void *pvUser);
746
747	/**
748	* Converts a link address to a segment:offset address.
749	*
750	* @returns IPRT status code.
751	*
752	* @param hLdrMod The module handle.
753	* @param LinkAddress The link address to convert.
754	* @param piSeg Where to return the segment index.
755	* @param poffSeg Where to return the segment offset.
756	*/
757	RTDECL(int) RTLdrLinkAddressToSegOffset(RTLDRMOD hLdrMod, RTLDRADDR LinkAddress, uint32_t *piSeg, PRTLDRADDR poffSeg);
758
759	/**
760	* Converts a link address to an image relative virtual address (RVA).
761	*
762	* @returns IPRT status code.
763	*
764	* @param hLdrMod The module handle.
765	* @param LinkAddress The link address to convert.
766	* @param pRva Where to return the RVA.
767	*/
768	RTDECL(int) RTLdrLinkAddressToRva(RTLDRMOD hLdrMod, RTLDRADDR LinkAddress, PRTLDRADDR pRva);
769
770	/**
771	* Converts an image relative virtual address (RVA) to a segment:offset.
772	*
773	* @returns IPRT status code.
774	*
775	* @param hLdrMod The module handle.
776	* @param Rva The link address to convert.
777	* @param piSeg Where to return the segment index.
778	* @param poffSeg Where to return the segment offset.
779	*/
780	RTDECL(int) RTLdrSegOffsetToRva(RTLDRMOD hLdrMod, uint32_t iSeg, RTLDRADDR offSeg, PRTLDRADDR pRva);
781
782	/**
783	* Converts a segment:offset into an image relative virtual address (RVA).
784	*
785	* @returns IPRT status code.
786	*
787	* @param hLdrMod The module handle.
788	* @param iSeg The segment index.
789	* @param offSeg The segment offset.
790	* @param pRva Where to return the RVA.
791	*/
792	RTDECL(int) RTLdrRvaToSegOffset(RTLDRMOD hLdrMod, RTLDRADDR Rva, uint32_t *piSeg, PRTLDRADDR poffSeg);
793
794	/**
795	* Gets the image format.
796	*
797	* @returns Valid image format on success. RTLDRFMT_INVALID on invalid handle or
798	* other errors.
799	* @param hLdrMod The module handle.
800	*/
801	RTDECL(RTLDRFMT) RTLdrGetFormat(RTLDRMOD hLdrMod);
802
803	/**
804	* Gets the image type.
805	*
806	* @returns Valid image type value on success. RTLDRTYPE_INVALID on
807	* invalid handle or other errors.
808	* @param hLdrMod The module handle.
809	*/
810	RTDECL(RTLDRTYPE) RTLdrGetType(RTLDRMOD hLdrMod);
811
812	/**
813	* Gets the image endian-ness.
814	*
815	* @returns Valid image endian value on success. RTLDRENDIAN_INVALID on invalid
816	* handle or other errors.
817	* @param hLdrMod The module handle.
818	*/
819	RTDECL(RTLDRENDIAN) RTLdrGetEndian(RTLDRMOD hLdrMod);
820
821	/**
822	* Gets the image endian-ness.
823	*
824	* @returns Valid image architecture value on success.
825	* RTLDRARCH_INVALID on invalid handle or other errors.
826	* @param hLdrMod The module handle.
827	*/
828	RTDECL(RTLDRARCH) RTLdrGetArch(RTLDRMOD hLdrMod);
829
830	/**
831	* Loader properties that can be queried thru RTLdrQueryProp.
832	*/
833	typedef enum RTLDRPROP
834	{
835	RTLDRPROP_INVALID = 0,
836	/** The image UUID (Mach-O).
837	* Returns a RTUUID in the buffer. */
838	RTLDRPROP_UUID,
839	/** The image timestamp in seconds, genrally since unix epoc.
840	* Returns a 32-bit or 64-bit signed integer value in the buffer. */
841	RTLDRPROP_TIMESTAMP_SECONDS,
842	/** End of valid properties. */
843	RTLDRPROP_END,
844	/** Blow the type up to 32 bits. */
845	RTLDRPROP_32BIT_HACK = 0x7fffffff
846	} RTLDRPROP;
847
848	/**
849	* Generic method for querying image properties.
850	*
851	* @returns IPRT status code.
852	* @retval VERR_NOT_SUPPORTED if the property query isn't supported (either all
853	* or that specific property). The caller must handle this result.
854	* @retval VERR_NOT_FOUND the property was not found in the module. The caller
855	* must also normally deal with this.
856	* @retval VERR_INVALID_FUNCTION if the function value is wrong.
857	* @retval VERR_INVALID_PARAMETER if the buffer size is wrong.
858	* @retval VERR_INVALID_HANDLE if the handle is invalid.
859	*
860	* @param hLdrMod The module handle.
861	* @param enmLdrProp The property to query.
862	* @param pvBuf Pointer to the return buffer.
863	* @param cbBuf The size of the return buffer.
864	*/
865	RTDECL(int) RTLdrQueryProp(RTLDRMOD hLdrMod, RTLDRPROP enmProp, void *pvBuf, size_t cbBuf);
866
867	RT_C_DECLS_END
868
869	/** @} */
870
871	#endif
872

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

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

Download in other formats: