ldr.h@ 46157

Last change on this file since 46157 was 46113, checked in by vboxsync, 12 years ago
Implemented debug module that uses the exported symbols. This will work on all hosts. :-)
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 24.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	* Gets the default file suffix for DLL/SO/DYLIB/whatever.
55	*
56	* @returns The stuff (readonly).
57	*/
58	RTDECL(const char *) RTLdrGetSuff(void);
59
60	/**
61	* Checks if a library is loadable or not.
62	*
63	* This may attempt load and unload the library.
64	*
65	* @returns true/false accordingly.
66	* @param pszFilename Image filename.
67	*/
68	RTDECL(bool) RTLdrIsLoadable(const char *pszFilename);
69
70	/**
71	* Loads a dynamic load library (/shared object) image file using native
72	* OS facilities.
73	*
74	* The filename will be appended the default DLL/SO extension of
75	* the platform if it have been omitted. This means that it's not
76	* possible to load DLLs/SOs with no extension using this interface,
77	* but that's not a bad tradeoff.
78	*
79	* If no path is specified in the filename, the OS will usually search it's library
80	* path to find the image file.
81	*
82	* @returns iprt status code.
83	* @param pszFilename Image filename.
84	* @param phLdrMod Where to store the handle to the loader module.
85	*/
86	RTDECL(int) RTLdrLoad(const char *pszFilename, PRTLDRMOD phLdrMod);
87
88	/**
89	* Loads a dynamic load library (/shared object) image file using native
90	* OS facilities.
91	*
92	* The filename will be appended the default DLL/SO extension of
93	* the platform if it have been omitted. This means that it's not
94	* possible to load DLLs/SOs with no extension using this interface,
95	* but that's not a bad tradeoff.
96	*
97	* If no path is specified in the filename, the OS will usually search it's library
98	* path to find the image file.
99	*
100	* @returns iprt status code.
101	* @param pszFilename Image filename.
102	* @param phLdrMod Where to store the handle to the loader module.
103	* @param fFlags See RTLDRLOAD_FLAGS_XXX.
104	* @param pErrInfo Where to return extended error information. Optional.
105	*/
106	RTDECL(int) RTLdrLoadEx(const char *pszFilename, PRTLDRMOD phLdrMod, uint32_t fFlags, PRTERRINFO pErrInfo);
107
108	/** @defgroup RTLDRLOAD_FLAGS_XXX RTLdrLoadEx flags.
109	* @{ */
110	/** Symbols defined in this library are not made available to resolve
111	* references in subsequently loaded libraries (default). */
112	#define RTLDRLOAD_FLAGS_LOCAL UINT32_C(0)
113	/** Symbols defined in this library will be made available for symbol
114	* resolution of subsequently loaded libraries. */
115	#define RTLDRLOAD_FLAGS_GLOBAL RT_BIT_32(0)
116	/** The mask of valid flag bits. */
117	#define RTLDRLOAD_FLAGS_VALID_MASK UINT32_C(0x00000001)
118	/** @} */
119
120	/**
121	* Loads a dynamic load library (/shared object) image file residing in the
122	* RTPathAppPrivateArch() directory.
123	*
124	* Suffix is not required.
125	*
126	* @returns iprt status code.
127	* @param pszFilename Image filename. No path.
128	* @param phLdrMod Where to store the handle to the loaded module.
129	*/
130	RTDECL(int) RTLdrLoadAppPriv(const char *pszFilename, PRTLDRMOD phLdrMod);
131
132	/**
133	* Image architecuture specifier for RTLdrOpenEx.
134	*/
135	typedef enum RTLDRARCH
136	{
137	RTLDRARCH_INVALID = 0,
138	/** Whatever. */
139	RTLDRARCH_WHATEVER,
140	/** The host architecture. */
141	RTLDRARCH_HOST,
142	/** 32-bit x86. */
143	RTLDRARCH_X86_32,
144	/** AMD64 (64-bit x86 if you like). */
145	RTLDRARCH_AMD64,
146	/** End of the valid values. */
147	RTLDRARCH_END,
148	/** Make sure the type is a full 32-bit. */
149	RTLDRARCH_32BIT_HACK = 0x7fffffff
150	} RTLDRARCH;
151	/** Pointer to a RTLDRARCH. */
152	typedef RTLDRARCH *PRTLDRARCH;
153
154	/** @name RTLDR_O_XXX - RTLdrOpen flags.
155	* @{ */
156	/** Open for debugging or introspection reasons.
157	* This will skip a few of the stricter validations when loading images. */
158	#define RTLDR_O_FOR_DEBUG RT_BIT_32(0)
159	/** Mask of valid flags. */
160	#define RTLDR_O_VALID_MASK UINT32_C(0x00000001)
161	/** @} */
162
163	/**
164	* Open a binary image file, extended version.
165	*
166	* @returns iprt status code.
167	* @param pszFilename Image filename.
168	* @param fFlags Valid RTLDR_O_XXX combination.
169	* @param enmArch CPU architecture specifier for the image to be loaded.
170	* @param phLdrMod Where to store the handle to the loader module.
171	*/
172	RTDECL(int) RTLdrOpen(const char *pszFilename, uint32_t fFlags, RTLDRARCH enmArch, PRTLDRMOD phLdrMod);
173
174	/**
175	* Opens a binary image file using kLdr.
176	*
177	* @returns iprt status code.
178	* @param pszFilename Image filename.
179	* @param phLdrMod Where to store the handle to the loaded module.
180	* @param fFlags Valid RTLDR_O_XXX combination.
181	* @param enmArch CPU architecture specifier for the image to be loaded.
182	* @remark Primarily for testing the loader.
183	*/
184	RTDECL(int) RTLdrOpenkLdr(const char *pszFilename, uint32_t fFlags, RTLDRARCH enmArch, PRTLDRMOD phLdrMod);
185
186
187	/**
188	* Called to read @a cb bytes at @a off into @a pvBuf.
189	*
190	* @returns IPRT status code
191	* @param pvBuf The output buffer.
192	* @param cb The number of bytes to read.
193	* @param off Where to start reading.
194	* @param pvUser The user parameter.
195	*/
196	typedef DECLCALLBACK(int) FNRTLDRRDRMEMREAD(void pvBuf, size_t cb, size_t off, void pvUser);
197	/** Pointer to a RTLdrOpenInMemory reader callback. */
198	typedef FNRTLDRRDRMEMREAD *PFNRTLDRRDRMEMREAD;
199
200	/**
201	* Called to when the module is unloaded (or done loading) to release resources
202	* associated with it (@a pvUser).
203	*
204	* @returns IPRT status code
205	* @param pvUser The user parameter.
206	*/
207	typedef DECLCALLBACK(void) FNRTLDRRDRMEMDTOR(void *pvUser);
208	/** Pointer to a RTLdrOpenInMemory destructor callback. */
209	typedef FNRTLDRRDRMEMDTOR *PFNRTLDRRDRMEMDTOR;
210
211	/**
212	* Open a in-memory image or an image with a custom reader callback.
213	*
214	* @returns IPRT status code.
215	* @param pszName The image name.
216	* @param fFlags Valid RTLDR_O_XXX combination.
217	* @param enmArch CPU architecture specifier for the image to be loaded.
218	* @param cbImage The size of the image (fake file).
219	* @param pfnRead The read function. If NULL is passed in, a default
220	* reader function is provided that assumes @a pvUser
221	* points to the raw image bits, at least @a cbImage of
222	* valid memory.
223	* @param pfnDtor The destructor function. If NULL is passed, a default
224	* destructor will be provided that passes @a pvUser to
225	* RTMemFree.
226	* @param pvUser The user argument or, if any of the callbacks are NULL,
227	* a pointer to a memory block.
228	* @param phLdrMod Where to return the module handle.
229	*
230	* @remarks With the exception of invalid @a pfnDtor and/or @a pvUser
231	* parameters, the pfnDtor methods (or the default one if NULL) will
232	* always be invoked. The destruction of pvUser is entirely in the
233	* hands of this method once it's called.
234	*/
235	RTDECL(int) RTLdrOpenInMemory(const char *pszName, uint32_t fFlags, RTLDRARCH enmArch, size_t cbImage,
236	PFNRTLDRRDRMEMREAD pfnRead, PFNRTLDRRDRMEMDTOR pfnDtor, void *pvUser,
237	PRTLDRMOD phLdrMod);
238
239	/**
240	* Closes a loader module handle.
241	*
242	* The handle can be obtained using any of the RTLdrLoad(), RTLdrOpen()
243	* and RTLdrOpenInMemory() functions.
244	*
245	* @returns iprt status code.
246	* @param hLdrMod The loader module handle.
247	*/
248	RTDECL(int) RTLdrClose(RTLDRMOD hLdrMod);
249
250	/**
251	* Gets the address of a named exported symbol.
252	*
253	* @returns iprt status code.
254	* @param hLdrMod The loader module handle.
255	* @param pszSymbol Symbol name.
256	* @param ppvValue Where to store the symbol value. Note that this is restricted to the
257	* pointer size used on the host!
258	*/
259	RTDECL(int) RTLdrGetSymbol(RTLDRMOD hLdrMod, const char pszSymbol, void *ppvValue);
260
261	/**
262	* Gets the address of a named exported symbol.
263	*
264	* This function differs from the plain one in that it can deal with
265	* both GC and HC address sizes, and that it can calculate the symbol
266	* value relative to any given base address.
267	*
268	* @returns iprt status code.
269	* @param hLdrMod The loader module handle.
270	* @param pvBits Optional pointer to the loaded image.
271	* Set this to NULL if no RTLdrGetBits() processed image bits are available.
272	* Not supported for RTLdrLoad() images.
273	* @param BaseAddress Image load address.
274	* Not supported for RTLdrLoad() images.
275	* @param pszSymbol Symbol name.
276	* @param pValue Where to store the symbol value.
277	*/
278	RTDECL(int) RTLdrGetSymbolEx(RTLDRMOD hLdrMod, const void pvBits, RTLDRADDR BaseAddress, const char pszSymbol,
279	PRTLDRADDR pValue);
280
281	/**
282	* Gets the size of the loaded image.
283	*
284	* This is not necessarily available for images that has been loaded using
285	* RTLdrLoad().
286	*
287	* @returns image size (in bytes).
288	* @returns ~(size_t)0 on if not available.
289	* @param hLdrMod Handle to the loader module.
290	*/
291	RTDECL(size_t) RTLdrSize(RTLDRMOD hLdrMod);
292
293	/**
294	* Resolve an external symbol during RTLdrGetBits().
295	*
296	* @returns iprt status code.
297	* @param hLdrMod The loader module handle.
298	* @param pszModule Module name.
299	* @param pszSymbol Symbol name, NULL if uSymbol should be used.
300	* @param uSymbol Symbol ordinal, ~0 if pszSymbol should be used.
301	* @param pValue Where to store the symbol value (address).
302	* @param pvUser User argument.
303	*/
304	typedef DECLCALLBACK(int) RTLDRIMPORT(RTLDRMOD hLdrMod, const char pszModule, const char pszSymbol, unsigned uSymbol,
305	PRTLDRADDR pValue, void *pvUser);
306	/** Pointer to a FNRTLDRIMPORT() callback function. */
307	typedef RTLDRIMPORT *PFNRTLDRIMPORT;
308
309	/**
310	* Loads the image into a buffer provided by the user and applies fixups
311	* for the given base address.
312	*
313	* @returns iprt status code.
314	* @param hLdrMod The load module handle.
315	* @param pvBits Where to put the bits.
316	* Must be as large as RTLdrSize() suggests.
317	* @param BaseAddress The base address.
318	* @param pfnGetImport Callback function for resolving imports one by one.
319	* @param pvUser User argument for the callback.
320	* @remark Not supported for RTLdrLoad() images.
321	*/
322	RTDECL(int) RTLdrGetBits(RTLDRMOD hLdrMod, void pvBits, RTLDRADDR BaseAddress, PFNRTLDRIMPORT pfnGetImport, void pvUser);
323
324	/**
325	* Relocates bits after getting them.
326	* Useful for code which moves around a bit.
327	*
328	* @returns iprt status code.
329	* @param hLdrMod The loader module handle.
330	* @param pvBits Where the image bits are.
331	* Must have been passed to RTLdrGetBits().
332	* @param NewBaseAddress The new base address.
333	* @param OldBaseAddress The old base address.
334	* @param pfnGetImport Callback function for resolving imports one by one.
335	* @param pvUser User argument for the callback.
336	* @remark Not supported for RTLdrLoad() images.
337	*/
338	RTDECL(int) RTLdrRelocate(RTLDRMOD hLdrMod, void *pvBits, RTLDRADDR NewBaseAddress, RTLDRADDR OldBaseAddress,
339	PFNRTLDRIMPORT pfnGetImport, void *pvUser);
340
341	/**
342	* Enumeration callback function used by RTLdrEnumSymbols().
343	*
344	* @returns iprt status code. Failure will stop the enumeration.
345	* @param hLdrMod The loader module handle.
346	* @param pszSymbol Symbol name. NULL if ordinal only.
347	* @param uSymbol Symbol ordinal, ~0 if not used.
348	* @param Value Symbol value.
349	* @param pvUser The user argument specified to RTLdrEnumSymbols().
350	*/
351	typedef DECLCALLBACK(int) RTLDRENUMSYMS(RTLDRMOD hLdrMod, const char pszSymbol, unsigned uSymbol, RTLDRADDR Value, void pvUser);
352	/** Pointer to a RTLDRENUMSYMS() callback function. */
353	typedef RTLDRENUMSYMS *PFNRTLDRENUMSYMS;
354
355	/**
356	* Enumerates all symbols in a module.
357	*
358	* @returns iprt status code.
359	* @param hLdrMod The loader module handle.
360	* @param fFlags Flags indicating what to return and such.
361	* @param pvBits Optional pointer to the loaded image. (RTLDR_ENUM_SYMBOL_FLAGS_*)
362	* Set this to NULL if no RTLdrGetBits() processed image bits are available.
363	* @param BaseAddress Image load address.
364	* @param pfnCallback Callback function.
365	* @param pvUser User argument for the callback.
366	* @remark Not supported for RTLdrLoad() images.
367	*/
368	RTDECL(int) RTLdrEnumSymbols(RTLDRMOD hLdrMod, unsigned fFlags, const void pvBits, RTLDRADDR BaseAddress, PFNRTLDRENUMSYMS pfnCallback, void pvUser);
369
370	/** @name RTLdrEnumSymbols flags.
371	* @{ */
372	/** Returns ALL kinds of symbols. The default is to only return public/exported symbols. */
373	#define RTLDR_ENUM_SYMBOL_FLAGS_ALL RT_BIT(1)
374	/** Ignore forwarders (for use with RTLDR_ENUM_SYMBOL_FLAGS_ALL). */
375	#define RTLDR_ENUM_SYMBOL_FLAGS_NO_FWD RT_BIT(2)
376	/** @} */
377
378
379	/**
380	* Debug info type (as far the loader can tell).
381	*/
382	typedef enum RTLDRDBGINFOTYPE
383	{
384	/** The invalid 0 value. */
385	RTLDRDBGINFOTYPE_INVALID = 0,
386	/** Unknown debug info format. */
387	RTLDRDBGINFOTYPE_UNKNOWN,
388	/** Stabs. */
389	RTLDRDBGINFOTYPE_STABS,
390	/** Debug With Arbitrary Record Format (DWARF). */
391	RTLDRDBGINFOTYPE_DWARF,
392	/** Debug With Arbitrary Record Format (DWARF), in external file (DWO). */
393	RTLDRDBGINFOTYPE_DWARF_DWO,
394	/** Microsoft Codeview debug info. */
395	RTLDRDBGINFOTYPE_CODEVIEW,
396	/** Microsoft Codeview debug info, in external v2.0+ program database (PDB). */
397	RTLDRDBGINFOTYPE_CODEVIEW_PDB20,
398	/** Microsoft Codeview debug info, in external v7.0+ program database (PDB). */
399	RTLDRDBGINFOTYPE_CODEVIEW_PDB70,
400	/** Microsoft Codeview debug info, in external file (DBG). */
401	RTLDRDBGINFOTYPE_CODEVIEW_DBG,
402	/** Watcom debug info. */
403	RTLDRDBGINFOTYPE_WATCOM,
404	/** IBM High Level Language debug info.. */
405	RTLDRDBGINFOTYPE_HLL,
406	/** The end of the valid debug info values (exclusive). */
407	RTLDRDBGINFOTYPE_END,
408	/** Blow the type up to 32-bits. */
409	RTLDRDBGINFOTYPE_32BIT_HACK = 0x7fffffff
410	} RTLDRDBGINFOTYPE;
411
412
413	/**
414	* Debug info details for the enumeration callback.
415	*/
416	typedef struct RTLDRDBGINFO
417	{
418	/** The kind of debug info. */
419	RTLDRDBGINFOTYPE enmType;
420	/** The debug info ordinal number / id. */
421	uint32_t iDbgInfo;
422	/** The file offset if this type has one specific location in the executable
423	* image file. This is -1 if there isn't any specific file location. */
424	RTFOFF offFile;
425	/** The link address of the debug info if it's loadable. NIL_RTLDRADDR if not
426	* loadable*/
427	RTLDRADDR LinkAddress;
428	/** The size of the debug information. -1 is used if this isn't applicable.*/
429	RTLDRADDR cb;
430	/** This is set if the debug information is found in an external file. NULL
431	* if no external file involved.
432	* @note Putting it outside the union to allow lazy callback implementation. */
433	const char *pszExtFile;
434	/** Type (enmType) specific information. */
435	union
436	{
437	/** RTLDRDBGINFOTYPE_DWARF */
438	struct
439	{
440	/** The section name. */
441	const char *pszSection;
442	} Dwarf;
443
444	/** RTLDRDBGINFOTYPE_DWARF_DWO */
445	struct
446	{
447	/** The CRC32 of the external file. */
448	uint32_t uCrc32;
449	} Dwo;
450
451	/** RTLDRDBGINFOTYPE_CODEVIEW_PDB20, RTLDRDBGINFOTYPE_CODEVIEW_DBG */
452	struct
453	{
454	/** The PE image size. */
455	uint32_t cbImage;
456	/** The timestamp. */
457	uint32_t uTimestamp;
458	/** The major version from the entry. */
459	uint32_t uMajorVer;
460	/** The minor version from the entry. */
461	uint32_t uMinorVer;
462	} Cv;
463
464	/** RTLDRDBGINFOTYPE_CODEVIEW_DBG */
465	struct
466	{
467	/** The PE image size. */
468	uint32_t cbImage;
469	/** The timestamp. */
470	uint32_t uTimestamp;
471	} Dbg;
472
473	/** RTLDRDBGINFOTYPE_CODEVIEW_PDB20*/
474	struct
475	{
476	/** The PE image size. */
477	uint32_t cbImage;
478	/** The timestamp. */
479	uint32_t uTimestamp;
480	/** The PDB age. */
481	uint32_t uAge;
482	} Pdb20;
483
484	/** RTLDRDBGINFOTYPE_CODEVIEW_PDB70 */
485	struct
486	{
487	/** The PE image size. */
488	uint32_t cbImage;
489	/** The PDB age. */
490	uint32_t uAge;
491	/** The UUID. */
492	RTUUID Uuid;
493	} Pdb70;
494	} u;
495	} RTLDRDBGINFO;
496	/** Pointer to debug info details. */
497	typedef RTLDRDBGINFO *PRTLDRDBGINFO;
498	/** Pointer to read only debug info details. */
499	typedef RTLDRDBGINFO const *PCRTLDRDBGINFO;
500
501
502	/**
503	* Debug info enumerator callback.
504	*
505	* @returns VINF_SUCCESS to continue the enumeration. Any other status code
506	* will cause RTLdrEnumDbgInfo to immediately return with that status.
507	*
508	* @param hLdrMod The module handle.
509	* @param pDbgInfo Pointer to a read only structure with the details.
510	* @param pvUser The user parameter specified to RTLdrEnumDbgInfo.
511	*/
512	typedef DECLCALLBACK(int) FNRTLDRENUMDBG(RTLDRMOD hLdrMod, PCRTLDRDBGINFO pDbgInfo, void *pvUser);
513	/** Pointer to a debug info enumerator callback. */
514	typedef FNRTLDRENUMDBG *PFNRTLDRENUMDBG;
515
516	/**
517	* Enumerate the debug info contained in the executable image.
518	*
519	* @returns IPRT status code or whatever pfnCallback returns.
520	*
521	* @param hLdrMod The module handle.
522	* @param pvBits Optional pointer to bits returned by
523	* RTLdrGetBits(). This can be used by some module
524	* interpreters to reduce memory consumption.
525	* @param pfnCallback The callback function.
526	* @param pvUser The user argument.
527	*/
528	RTDECL(int) RTLdrEnumDbgInfo(RTLDRMOD hLdrMod, const void pvBits, PFNRTLDRENUMDBG pfnCallback, void pvUser);
529
530
531	/**
532	* Loader segment.
533	*/
534	typedef struct RTLDRSEG
535	{
536	/** The segment name. (Might not be zero terminated!) */
537	const char *pchName;
538	/** The length of the segment name. */
539	uint32_t cchName;
540	/** The flat selector to use for the segment (i.e. data/code).
541	* Primarily a way for the user to specify selectors for the LX/LE and NE interpreters. */
542	uint16_t SelFlat;
543	/** The 16-bit selector to use for the segment.
544	* Primarily a way for the user to specify selectors for the LX/LE and NE interpreters. */
545	uint16_t Sel16bit;
546	/** Segment flags. */
547	uint32_t fFlags;
548	/** The segment protection (RTMEM_PROT_XXX). */
549	uint32_t fProt;
550	/** The size of the segment. */
551	RTLDRADDR cb;
552	/** The required segment alignment.
553	* The to 0 if the segment isn't supposed to be mapped. */
554	RTLDRADDR Alignment;
555	/** The link address.
556	* Set to NIL_RTLDRADDR if the segment isn't supposed to be mapped or if
557	* the image doesn't have link addresses. */
558	RTLDRADDR LinkAddress;
559	/** File offset of the segment.
560	* Set to -1 if no file backing (like BSS). */
561	RTFOFF offFile;
562	/** Size of the file bits of the segment.
563	* Set to -1 if no file backing (like BSS). */
564	RTFOFF cbFile;
565	/** The relative virtual address when mapped.
566	* Set to NIL_RTLDRADDR if the segment isn't supposed to be mapped. */
567	RTLDRADDR RVA;
568	/** The size of the segment including the alignment gap up to the next segment when mapped.
569	* This is set to NIL_RTLDRADDR if not implemented. */
570	RTLDRADDR cbMapped;
571	} RTLDRSEG;
572	/** Pointer to a loader segment. */
573	typedef RTLDRSEG *PRTLDRSEG;
574	/** Pointer to a read only loader segment. */
575	typedef RTLDRSEG const *PCRTLDRSEG;
576
577
578	/** @name Segment flags
579	* @{ */
580	/** The segment is 16-bit. When not set the default of the target architecture is assumed. */
581	#define RTLDRSEG_FLAG_16BIT UINT32_C(1)
582	/** The segment requires a 16-bit selector alias. (OS/2) */
583	#define RTLDRSEG_FLAG_OS2_ALIAS16 UINT32_C(2)
584	/** Conforming segment (x86 weirdness). (OS/2) */
585	#define RTLDRSEG_FLAG_OS2_CONFORM UINT32_C(4)
586	/** IOPL (ring-2) segment. (OS/2) */
587	#define RTLDRSEG_FLAG_OS2_IOPL UINT32_C(8)
588	/** @} */
589
590	/**
591	* Segment enumerator callback.
592	*
593	* @returns VINF_SUCCESS to continue the enumeration. Any other status code
594	* will cause RTLdrEnumSegments to immediately return with that
595	* status.
596	*
597	* @param hLdrMod The module handle.
598	* @param pSeg The segment information.
599	* @param pvUser The user parameter specified to RTLdrEnumSegments.
600	*/
601	typedef DECLCALLBACK(int) FNRTLDRENUMSEGS(RTLDRMOD hLdrMod, PCRTLDRSEG pSeg, void *pvUser);
602	/** Pointer to a segment enumerator callback. */
603	typedef FNRTLDRENUMSEGS *PFNRTLDRENUMSEGS;
604
605	/**
606	* Enumerate the debug info contained in the executable image.
607	*
608	* @returns IPRT status code or whatever pfnCallback returns.
609	*
610	* @param hLdrMod The module handle.
611	* @param pfnCallback The callback function.
612	* @param pvUser The user argument.
613	*/
614	RTDECL(int) RTLdrEnumSegments(RTLDRMOD hLdrMod, PFNRTLDRENUMSEGS pfnCallback, void *pvUser);
615
616	/**
617	* Converts a link address to a segment:offset address.
618	*
619	* @returns IPRT status code.
620	*
621	* @param hLdrMod The module handle.
622	* @param LinkAddress The link address to convert.
623	* @param piSeg Where to return the segment index.
624	* @param poffSeg Where to return the segment offset.
625	*/
626	RTDECL(int) RTLdrLinkAddressToSegOffset(RTLDRMOD hLdrMod, RTLDRADDR LinkAddress, uint32_t *piSeg, PRTLDRADDR poffSeg);
627
628	/**
629	* Converts a link address to an image relative virtual address (RVA).
630	*
631	* @returns IPRT status code.
632	*
633	* @param hLdrMod The module handle.
634	* @param LinkAddress The link address to convert.
635	* @param pRva Where to return the RVA.
636	*/
637	RTDECL(int) RTLdrLinkAddressToRva(RTLDRMOD hLdrMod, RTLDRADDR LinkAddress, PRTLDRADDR pRva);
638
639	/**
640	* Converts an image relative virtual address (RVA) to a segment:offset.
641	*
642	* @returns IPRT status code.
643	*
644	* @param hLdrMod The module handle.
645	* @param Rva The link address to convert.
646	* @param piSeg Where to return the segment index.
647	* @param poffSeg Where to return the segment offset.
648	*/
649	RTDECL(int) RTLdrSegOffsetToRva(RTLDRMOD hLdrMod, uint32_t iSeg, RTLDRADDR offSeg, PRTLDRADDR pRva);
650
651	/**
652	* Converts a segment:offset into an image relative virtual address (RVA).
653	*
654	* @returns IPRT status code.
655	*
656	* @param hLdrMod The module handle.
657	* @param iSeg The segment index.
658	* @param offSeg The segment offset.
659	* @param pRva Where to return the RVA.
660	*/
661	RTDECL(int) RTLdrRvaToSegOffset(RTLDRMOD hLdrMod, RTLDRADDR Rva, uint32_t *piSeg, PRTLDRADDR poffSeg);
662
663	RT_C_DECLS_END
664
665	/** @} */
666
667	#endif
668

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

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

Download in other formats: