ldr.h@ 47356

Last change on this file since 47356 was 46593, checked in by vboxsync, 12 years ago
updates
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 29.0 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	RT_C_DECLS_END
832
833	/** @} */
834
835	#endif
836

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

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

Download in other formats: