dbg.h@ 40451

Last change on this file since 40451 was 36555, checked in by vboxsync, 14 years ago
Use DECLHIDDEN, especially in IPRT.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 45.1 KB

Line
1	/* $Id: dbg.h 36555 2011-04-05 12:34:09Z vboxsync $ */
2	/** @file
3	* IPRT - Debugging Routines.
4	*/
5
6	/*
7	* Copyright (C) 2008-2009 Oracle Corporation
8	*
9	* This file is part of VirtualBox Open Source Edition (OSE), as
10	* available from http://www.virtualbox.org. This file is free software;
11	* you can redistribute it and/or modify it under the terms of the GNU
12	* General Public License (GPL) as published by the Free Software
13	* Foundation, in version 2 as it comes in the "COPYING" file of the
14	* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
15	* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
16	*
17	* The contents of this file may alternatively be used under the terms
18	* of the Common Development and Distribution License Version 1.0
19	* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
20	* VirtualBox OSE distribution, in which case the provisions of the
21	* CDDL are applicable instead of those of the GPL.
22	*
23	* You may elect to license modified versions of this file under the
24	* terms and conditions of either the GPL or the CDDL or both.
25	*/
26
27	#ifndef ___iprt_dbg_h
28	#define ___iprt_dbg_h
29
30	#include <iprt/types.h>
31	#include <iprt/stdarg.h>
32
33	RT_C_DECLS_BEGIN
34
35	/** @defgroup grp_rt_dbg RTDbg - Debugging Routines
36	* @ingroup grp_rt
37	* @{
38	*/
39
40
41	/** Debug segment index. */
42	typedef uint32_t RTDBGSEGIDX;
43	/** Pointer to a debug segment index. */
44	typedef RTDBGSEGIDX *PRTDBGSEGIDX;
45	/** Pointer to a const debug segment index. */
46	typedef RTDBGSEGIDX const *PCRTDBGSEGIDX;
47	/** NIL debug segment index. */
48	#define NIL_RTDBGSEGIDX UINT32_C(0xffffffff)
49	/** The last normal segment index. */
50	#define RTDBGSEGIDX_LAST UINT32_C(0xffffffef)
51	/** Special segment index that indicates that the offset is a relative
52	* virtual address (RVA). I.e. an offset from the start of the module. */
53	#define RTDBGSEGIDX_RVA UINT32_C(0xfffffff0)
54	/** Special segment index that indicates that the offset is a absolute. */
55	#define RTDBGSEGIDX_ABS UINT32_C(0xfffffff1)
56	/** The last valid special segment index. */
57	#define RTDBGSEGIDX_SPECIAL_LAST RTDBGSEGIDX_ABS
58	/** The last valid special segment index. */
59	#define RTDBGSEGIDX_SPECIAL_FIRST (RTDBGSEGIDX_LAST + 1U)
60
61
62	/** Max length (including '\\0') of a segment name. */
63	#define RTDBG_SEGMENT_NAME_LENGTH (128 - 8 - 8 - 8 - 4 - 4)
64
65	/**
66	* Debug module segment.
67	*/
68	typedef struct RTDBGSEGMENT
69	{
70	/** The load address.
71	* RTUINTPTR_MAX if not applicable. */
72	RTUINTPTR Address;
73	/** The image relative virtual address of the segment.
74	* RTUINTPTR_MAX if not applicable. */
75	RTUINTPTR uRva;
76	/** The segment size. */
77	RTUINTPTR cb;
78	/** The segment flags. (reserved) */
79	uint32_t fFlags;
80	/** The segment index. */
81	RTDBGSEGIDX iSeg;
82	/** Symbol name. */
83	char szName[RTDBG_SEGMENT_NAME_LENGTH];
84	} RTDBGSEGMENT;
85	/** Pointer to a debug module segment. */
86	typedef RTDBGSEGMENT *PRTDBGSEGMENT;
87	/** Pointer to a const debug module segment. */
88	typedef RTDBGSEGMENT const *PCRTDBGSEGMENT;
89
90
91
92	/** Max length (including '\\0') of a symbol name. */
93	#define RTDBG_SYMBOL_NAME_LENGTH (384 - 8 - 8 - 8 - 4 - 4 - 8)
94
95	/**
96	* Debug symbol.
97	*/
98	typedef struct RTDBGSYMBOL
99	{
100	/** Symbol value (address).
101	* This depends a bit who you ask. It will be the same as offSeg when you
102	* as RTDbgMod, but the mapping address if you ask RTDbgAs. */
103	RTUINTPTR Value;
104	/** Symbol size. */
105	RTUINTPTR cb;
106	/** Offset into the segment specified by iSeg. */
107	RTUINTPTR offSeg;
108	/** Segment number. */
109	RTDBGSEGIDX iSeg;
110	/** Symbol Flags. (reserved). */
111	uint32_t fFlags;
112	/** Symbol ordinal.
113	* This is set to UINT32_MAX if the ordinals aren't supported. */
114	uint32_t iOrdinal;
115	/** Symbol name. */
116	char szName[RTDBG_SYMBOL_NAME_LENGTH];
117	} RTDBGSYMBOL;
118	/** Pointer to debug symbol. */
119	typedef RTDBGSYMBOL *PRTDBGSYMBOL;
120	/** Pointer to const debug symbol. */
121	typedef const RTDBGSYMBOL *PCRTDBGSYMBOL;
122
123	/**
124	* Allocate a new symbol structure.
125	*
126	* @returns Pointer to a new structure on success, NULL on failure.
127	*/
128	RTDECL(PRTDBGSYMBOL) RTDbgSymbolAlloc(void);
129
130	/**
131	* Duplicates a symbol structure.
132	*
133	* @returns Pointer to duplicate on success, NULL on failure.
134	*
135	* @param pSymInfo The symbol info to duplicate.
136	*/
137	RTDECL(PRTDBGSYMBOL) RTDbgSymbolDup(PCRTDBGSYMBOL pSymInfo);
138
139	/**
140	* Free a symbol structure previously allocated by a RTDbg method.
141	*
142	* @param pSymInfo The symbol info to free. NULL is ignored.
143	*/
144	RTDECL(void) RTDbgSymbolFree(PRTDBGSYMBOL pSymInfo);
145
146
147	/** Max length (including '\\0') of a debug info file name. */
148	#define RTDBG_FILE_NAME_LENGTH (260)
149
150
151	/**
152	* Debug line number information.
153	*/
154	typedef struct RTDBGLINE
155	{
156	/** Address.
157	* This depends a bit who you ask. It will be the same as offSeg when you
158	* as RTDbgMod, but the mapping address if you ask RTDbgAs. */
159	RTUINTPTR Address;
160	/** Offset into the segment specified by iSeg. */
161	RTUINTPTR offSeg;
162	/** Segment number. */
163	RTDBGSEGIDX iSeg;
164	/** Line number. */
165	uint32_t uLineNo;
166	/** Symbol ordinal.
167	* This is set to UINT32_MAX if the ordinals aren't supported. */
168	uint32_t iOrdinal;
169	/** Filename. */
170	char szFilename[RTDBG_FILE_NAME_LENGTH];
171	} RTDBGLINE;
172	/** Pointer to debug line number. */
173	typedef RTDBGLINE *PRTDBGLINE;
174	/** Pointer to const debug line number. */
175	typedef const RTDBGLINE *PCRTDBGLINE;
176
177	/**
178	* Allocate a new line number structure.
179	*
180	* @returns Pointer to a new structure on success, NULL on failure.
181	*/
182	RTDECL(PRTDBGLINE) RTDbgLineAlloc(void);
183
184	/**
185	* Duplicates a line number structure.
186	*
187	* @returns Pointer to duplicate on success, NULL on failure.
188	*
189	* @param pLine The line number to duplicate.
190	*/
191	RTDECL(PRTDBGLINE) RTDbgLineDup(PCRTDBGLINE pLine);
192
193	/**
194	* Free a line number structure previously allocated by a RTDbg method.
195	*
196	* @param pLine The line number to free. NULL is ignored.
197	*/
198	RTDECL(void) RTDbgLineFree(PRTDBGLINE pLine);
199
200
201	/** @defgroup grp_rt_dbgas RTDbgAs - Debug Address Space
202	* @{
203	*/
204
205	/**
206	* Creates an empty address space.
207	*
208	* @returns IPRT status code.
209	*
210	* @param phDbgAs Where to store the address space handle on success.
211	* @param FirstAddr The first address in the address space.
212	* @param LastAddr The last address in the address space.
213	* @param pszName The name of the address space.
214	*/
215	RTDECL(int) RTDbgAsCreate(PRTDBGAS phDbgAs, RTUINTPTR FirstAddr, RTUINTPTR LastAddr, const char *pszName);
216
217	/**
218	* Variant of RTDbgAsCreate that takes a name format string.
219	*
220	* @returns IPRT status code.
221	*
222	* @param phDbgAs Where to store the address space handle on success.
223	* @param FirstAddr The first address in the address space.
224	* @param LastAddr The last address in the address space.
225	* @param pszNameFmt The name format of the address space.
226	* @param va Format arguments.
227	*/
228	RTDECL(int) RTDbgAsCreateV(PRTDBGAS phDbgAs, RTUINTPTR FirstAddr, RTUINTPTR LastAddr, const char *pszNameFmt, va_list va);
229
230	/**
231	* Variant of RTDbgAsCreate that takes a name format string.
232	*
233	* @returns IPRT status code.
234	*
235	* @param phDbgAs Where to store the address space handle on success.
236	* @param FirstAddr The first address in the address space.
237	* @param LastAddr The last address in the address space.
238	* @param pszNameFmt The name format of the address space.
239	* @param ... Format arguments.
240	*/
241	RTDECL(int) RTDbgAsCreateF(PRTDBGAS phDbgAs, RTUINTPTR FirstAddr, RTUINTPTR LastAddr, const char *pszNameFmt, ...);
242
243	/**
244	* Retains a reference to the address space.
245	*
246	* @returns New reference count, UINT32_MAX on invalid handle (asserted).
247	*
248	* @param hDbgAs The address space handle.
249	*
250	* @remarks Will not take any locks.
251	*/
252	RTDECL(uint32_t) RTDbgAsRetain(RTDBGAS hDbgAs);
253
254	/**
255	* Release a reference to the address space.
256	*
257	* When the reference count reaches zero, the address space is destroyed.
258	* That means unlinking all the modules it currently contains, potentially
259	* causing some or all of them to be destroyed as they are managed by
260	* reference counting.
261	*
262	* @returns New reference count, UINT32_MAX on invalid handle (asserted).
263	*
264	* @param hDbgAs The address space handle. The NIL handle is quietly
265	* ignored and 0 is returned.
266	*
267	* @remarks Will not take any locks.
268	*/
269	RTDECL(uint32_t) RTDbgAsRelease(RTDBGAS hDbgAs);
270
271	/**
272	* Gets the name of an address space.
273	*
274	* @returns read only address space name.
275	* NULL if hDbgAs is invalid.
276	*
277	* @param hDbgAs The address space handle.
278	*
279	* @remarks Will not take any locks.
280	*/
281	RTDECL(const char *) RTDbgAsName(RTDBGAS hDbgAs);
282
283	/**
284	* Gets the first address in an address space.
285	*
286	* @returns The address.
287	* 0 if hDbgAs is invalid.
288	*
289	* @param hDbgAs The address space handle.
290	*
291	* @remarks Will not take any locks.
292	*/
293	RTDECL(RTUINTPTR) RTDbgAsFirstAddr(RTDBGAS hDbgAs);
294
295	/**
296	* Gets the last address in an address space.
297	*
298	* @returns The address.
299	* 0 if hDbgAs is invalid.
300	*
301	* @param hDbgAs The address space handle.
302	*
303	* @remarks Will not take any locks.
304	*/
305	RTDECL(RTUINTPTR) RTDbgAsLastAddr(RTDBGAS hDbgAs);
306
307	/**
308	* Gets the number of modules in the address space.
309	*
310	* This can be used together with RTDbgAsModuleByIndex
311	* to enumerate the modules.
312	*
313	* @returns The number of modules.
314	*
315	* @param hDbgAs The address space handle.
316	*
317	* @remarks Will not take any locks.
318	*/
319	RTDECL(uint32_t) RTDbgAsModuleCount(RTDBGAS hDbgAs);
320
321	/** @name Flags for RTDbgAsModuleLink and RTDbgAsModuleLinkSeg
322	* @{ */
323	/** Replace all conflicting module.
324	* (The conflicting modules will be removed the address space and their
325	* references released.) */
326	#define RTDBGASLINK_FLAGS_REPLACE RT_BIT_32(0)
327	/** Mask containing the valid flags. */
328	#define RTDBGASLINK_FLAGS_VALID_MASK UINT32_C(0x00000001)
329	/** @} */
330
331	/**
332	* Links a module into the address space at the give address.
333	*
334	* The size of the mapping is determined using RTDbgModImageSize().
335	*
336	* @returns IPRT status code.
337	* @retval VERR_OUT_OF_RANGE if the specified address will put the module
338	* outside the address space.
339	* @retval VERR_ADDRESS_CONFLICT if the mapping clashes with existing mappings.
340	*
341	* @param hDbgAs The address space handle.
342	* @param hDbgMod The module handle of the module to be linked in.
343	* @param ImageAddr The address to link the module at.
344	* @param fFlags See RTDBGASLINK_FLAGS_*.
345	*/
346	RTDECL(int) RTDbgAsModuleLink(RTDBGAS hDbgAs, RTDBGMOD hDbgMod, RTUINTPTR ImageAddr, uint32_t fFlags);
347
348	/**
349	* Links a segment into the address space at the give address.
350	*
351	* The size of the mapping is determined using RTDbgModSegmentSize().
352	*
353	* @returns IPRT status code.
354	* @retval VERR_OUT_OF_RANGE if the specified address will put the module
355	* outside the address space.
356	* @retval VERR_ADDRESS_CONFLICT if the mapping clashes with existing mappings.
357	*
358	* @param hDbgAs The address space handle.
359	* @param hDbgMod The module handle.
360	* @param iSeg The segment number (0-based) of the segment to be
361	* linked in.
362	* @param SegAddr The address to link the segment at.
363	* @param fFlags See RTDBGASLINK_FLAGS_*.
364	*/
365	RTDECL(int) RTDbgAsModuleLinkSeg(RTDBGAS hDbgAs, RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR SegAddr, uint32_t fFlags);
366
367	/**
368	* Unlinks all the mappings of a module from the address space.
369	*
370	* @returns IPRT status code.
371	* @retval VERR_NOT_FOUND if the module wasn't found.
372	*
373	* @param hDbgAs The address space handle.
374	* @param hDbgMod The module handle of the module to be unlinked.
375	*/
376	RTDECL(int) RTDbgAsModuleUnlink(RTDBGAS hDbgAs, RTDBGMOD hDbgMod);
377
378	/**
379	* Unlinks the mapping at the specified address.
380	*
381	* @returns IPRT status code.
382	* @retval VERR_NOT_FOUND if no module or segment is mapped at that address.
383	*
384	* @param hDbgAs The address space handle.
385	* @param Addr The address within the mapping to be unlinked.
386	*/
387	RTDECL(int) RTDbgAsModuleUnlinkByAddr(RTDBGAS hDbgAs, RTUINTPTR Addr);
388
389	/**
390	* Get a the handle of a module in the address space by is index.
391	*
392	* @returns A retained handle to the specified module. The caller must release
393	* the returned reference.
394	* NIL_RTDBGMOD if invalid index or handle.
395	*
396	* @param hDbgAs The address space handle.
397	* @param iModule The index of the module to get.
398	*
399	* @remarks The module indexes may change after calls to RTDbgAsModuleLink,
400	* RTDbgAsModuleLinkSeg, RTDbgAsModuleUnlink and
401	* RTDbgAsModuleUnlinkByAddr.
402	*/
403	RTDECL(RTDBGMOD) RTDbgAsModuleByIndex(RTDBGAS hDbgAs, uint32_t iModule);
404
405	/**
406	* Queries mapping module information by handle.
407	*
408	* @returns IPRT status code.
409	* @retval VERR_NOT_FOUND if no mapping was found at the specified address.
410	*
411	* @param hDbgAs The address space handle.
412	* @param Addr Address within the mapping of the module or segment.
413	* @param phMod Where to the return the retained module handle.
414	* Optional.
415	* @param pAddr Where to return the base address of the mapping.
416	* Optional.
417	* @param piSeg Where to return the segment index. This is set to
418	* NIL if the entire module is mapped as a single
419	* mapping. Optional.
420	*/
421	RTDECL(int) RTDbgAsModuleByAddr(RTDBGAS hDbgAs, RTUINTPTR Addr, PRTDBGMOD phMod, PRTUINTPTR pAddr, PRTDBGSEGIDX piSeg);
422
423	/**
424	* Queries mapping module information by name.
425	*
426	* @returns IPRT status code.
427	* @retval VERR_NOT_FOUND if no mapping was found at the specified address.
428	* @retval VERR_OUT_OF_RANGE if the name index was out of range.
429	*
430	* @param hDbgAs The address space handle.
431	* @param pszName The module name.
432	* @param iName There can be more than one module by the same name
433	* in an address space. This argument indicates which
434	* is meant. (0 based)
435	* @param phMod Where to the return the retained module handle.
436	*/
437	RTDECL(int) RTDbgAsModuleByName(RTDBGAS hDbgAs, const char *pszName, uint32_t iName, PRTDBGMOD phMod);
438
439	/**
440	* Information about a mapping.
441	*
442	* This is used by RTDbgAsModuleGetMapByIndex.
443	*/
444	typedef struct RTDBGASMAPINFO
445	{
446	/** The mapping address. */
447	RTUINTPTR Address;
448	/** The segment mapped there.
449	* This is NIL_RTDBGSEGIDX if the entire module image is mapped here. */
450	RTDBGSEGIDX iSeg;
451	} RTDBGASMAPINFO;
452	/** Pointer to info about an address space mapping. */
453	typedef RTDBGASMAPINFO *PRTDBGASMAPINFO;
454	/** Pointer to const info about an address space mapping. */
455	typedef RTDBGASMAPINFO const *PCRTDBGASMAPINFO;
456
457	/**
458	* Queries mapping information for a module given by index.
459	*
460	* @returns IRPT status code.
461	* @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
462	* @retval VERR_OUT_OF_RANGE if the name index was out of range.
463	* @retval VINF_BUFFER_OVERFLOW if the array is too small and the returned
464	* information is incomplete.
465	*
466	* @param hDbgAs The address space handle.
467	* @param iModule The index of the module to get.
468	* @param paMappings Where to return the mapping information. The buffer
469	* size is given by *pcMappings.
470	* @param pcMappings IN: Size of the paMappings array. OUT: The number of
471	* entries returned.
472	* @param fFlags Flags for reserved for future use. MBZ.
473	*
474	* @remarks See remarks for RTDbgAsModuleByIndex regarding the volatility of the
475	* iModule parameter.
476	*/
477	RTDECL(int) RTDbgAsModuleQueryMapByIndex(RTDBGAS hDbgAs, uint32_t iModule, PRTDBGASMAPINFO paMappings, uint32_t *pcMappings, uint32_t fFlags);
478
479	/**
480	* Adds a symbol to a module in the address space.
481	*
482	* @returns IPRT status code. See RTDbgModSymbolAdd for more specific ones.
483	* @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
484	* @retval VERR_NOT_FOUND if no module was found at the specified address.
485	* @retval VERR_NOT_SUPPORTED if the module interpret doesn't support adding
486	* custom symbols.
487	*
488	* @param hDbgAs The address space handle.
489	* @param pszSymbol The symbol name.
490	* @param Addr The address of the symbol.
491	* @param cb The size of the symbol.
492	* @param fFlags Symbol flags.
493	* @param piOrdinal Where to return the symbol ordinal on success. If
494	* the interpreter doesn't do ordinals, this will be set to
495	* UINT32_MAX. Optional
496	*/
497	RTDECL(int) RTDbgAsSymbolAdd(RTDBGAS hDbgAs, const char pszSymbol, RTUINTPTR Addr, RTUINTPTR cb, uint32_t fFlags, uint32_t piOrdinal);
498
499	/**
500	* Query a symbol by address.
501	*
502	* @returns IPRT status code. See RTDbgModSymbolAddr for more specific ones.
503	* @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
504	* @retval VERR_NOT_FOUND if the address couldn't be mapped to a module.
505	*
506	* @param hDbgAs The address space handle.
507	* @param Addr The address which closest symbol is requested.
508	* @param poffDisp Where to return the distance between the symbol
509	* and address. Optional.
510	* @param pSymbol Where to return the symbol info.
511	* @param phMod Where to return the module handle. Optional.
512	*/
513	RTDECL(int) RTDbgAsSymbolByAddr(RTDBGAS hDbgAs, RTUINTPTR Addr, PRTINTPTR poffDisp, PRTDBGSYMBOL pSymbol, PRTDBGMOD phMod);
514
515	/**
516	* Query a symbol by address.
517	*
518	* @returns IPRT status code. See RTDbgModSymbolAddrA for more specific ones.
519	* @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
520	* @retval VERR_NOT_FOUND if the address couldn't be mapped to a module.
521	*
522	* @param hDbgAs The address space handle.
523	* @param Addr The address which closest symbol is requested.
524	* @param poffDisp Where to return the distance between the symbol
525	* and address. Optional.
526	* @param ppSymInfo Where to return the pointer to the allocated symbol
527	* info. Always set. Free with RTDbgSymbolFree.
528	* @param phMod Where to return the module handle. Optional.
529	*/
530	RTDECL(int) RTDbgAsSymbolByAddrA(RTDBGAS hDbgAs, RTUINTPTR Addr, PRTINTPTR poffDisp, PRTDBGSYMBOL *ppSymInfo, PRTDBGMOD phMod);
531
532	/**
533	* Query a symbol by name.
534	*
535	* @returns IPRT status code.
536	* @retval VERR_SYMBOL_NOT_FOUND if not found.
537	*
538	* @param hDbgAs The address space handle.
539	* @param pszSymbol The symbol name. It is possible to limit the scope
540	* of the search by prefixing the symbol with a module
541	* name pattern followed by a bang (!) character.
542	* RTStrSimplePatternNMatch is used for the matching.
543	* @param pSymbol Where to return the symbol info.
544	* @param phMod Where to return the module handle. Optional.
545	*/
546	RTDECL(int) RTDbgAsSymbolByName(RTDBGAS hDbgAs, const char *pszSymbol, PRTDBGSYMBOL pSymbol, PRTDBGMOD phMod);
547
548	/**
549	* Query a symbol by name, allocating the returned symbol structure.
550	*
551	* @returns IPRT status code.
552	* @retval VERR_SYMBOL_NOT_FOUND if not found.
553	*
554	* @param hDbgAs The address space handle.
555	* @param pszSymbol The symbol name. See RTDbgAsSymbolByName for more.
556	* @param ppSymbol Where to return the pointer to the allocated
557	* symbol info. Always set. Free with RTDbgSymbolFree.
558	* @param phMod Where to return the module handle. Optional.
559	*/
560	RTDECL(int) RTDbgAsSymbolByNameA(RTDBGAS hDbgAs, const char pszSymbol, PRTDBGSYMBOL ppSymbol, PRTDBGMOD phMod);
561
562	/**
563	* Query a line number by address.
564	*
565	* @returns IPRT status code. See RTDbgModSymbolAddrA for more specific ones.
566	* @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
567	* @retval VERR_NOT_FOUND if the address couldn't be mapped to a module.
568	*
569	* @param hDbgAs The address space handle.
570	* @param Addr The address which closest symbol is requested.
571	* @param poffDisp Where to return the distance between the line
572	* number and address.
573	* @param pLine Where to return the line number information.
574	*/
575	RTDECL(int) RTDbgAs(RTDBGAS hDbgAs, RTUINTPTR Addr, PRTINTPTR poffDisp, PRTDBGLINE pLine);
576
577	/**
578	* Adds a line number to a module in the address space.
579	*
580	* @returns IPRT status code. See RTDbgModSymbolAdd for more specific ones.
581	* @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
582	* @retval VERR_NOT_FOUND if no module was found at the specified address.
583	* @retval VERR_NOT_SUPPORTED if the module interpret doesn't support adding
584	* custom symbols.
585	*
586	* @param hDbgAs The address space handle.
587	* @param pszFile The file name.
588	* @param uLineNo The line number.
589	* @param Addr The address of the symbol.
590	* @param piOrdinal Where to return the line number ordinal on success.
591	* If the interpreter doesn't do ordinals, this will be
592	* set to UINT32_MAX. Optional.
593	*/
594	RTDECL(int) RTDbgAsLineAdd(RTDBGAS hDbgAs, const char pszFile, uint32_t uLineNo, RTUINTPTR Addr, uint32_t piOrdinal);
595
596
597	/**
598	* Query a line number by address.
599	*
600	* @returns IPRT status code. See RTDbgModSymbolAddrA for more specific ones.
601	* @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
602	* @retval VERR_NOT_FOUND if the address couldn't be mapped to a module.
603	*
604	* @param hDbgAs The address space handle.
605	* @param Addr The address which closest symbol is requested.
606	* @param poffDisp Where to return the distance between the line
607	* number and address.
608	* @param pLine Where to return the line number information.
609	*/
610	RTDECL(int) RTDbgAsLineByAddr(RTDBGAS hDbgAs, RTUINTPTR Addr, PRTINTPTR poffDisp, PRTDBGLINE pLine);
611
612	/**
613	* Query a line number by address.
614	*
615	* @returns IPRT status code. See RTDbgModSymbolAddrA for more specific ones.
616	* @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
617	* @retval VERR_NOT_FOUND if the address couldn't be mapped to a module.
618	*
619	* @param hDbgAs The address space handle.
620	* @param Addr The address which closest symbol is requested.
621	* @param poffDisp Where to return the distance between the line
622	* number and address.
623	* @param ppLine Where to return the pointer to the allocated line
624	* number info. Always set. Free with RTDbgLineFree.
625	*/
626	RTDECL(int) RTDbgAsLineByAddrA(RTDBGAS hDbgAs, RTUINTPTR Addr, PRTINTPTR poffDisp, PRTDBGLINE *ppLine);
627
628	/** @todo Missing some bits here. */
629
630	/** @} */
631
632
633	/** @defgroup grp_rt_dbgmod RTDbgMod - Debug Module Interpreter
634	* @{
635	*/
636
637	/**
638	* Creates a module based on the default debug info container.
639	*
640	* This can be used to manually load a module and its symbol. The primary user
641	* group is the debug info interpreters, which use this API to create an
642	* efficient debug info container behind the scenes and forward all queries to
643	* it once the info has been loaded.
644	*
645	* @returns IPRT status code.
646	*
647	* @param phDbgMod Where to return the module handle.
648	* @param pszName The name of the module (mandatory).
649	* @param cbSeg The size of initial segment. If zero, segments will
650	* have to be added manually using RTDbgModSegmentAdd.
651	* @param fFlags Flags reserved for future extensions, MBZ for now.
652	*/
653	RTDECL(int) RTDbgModCreate(PRTDBGMOD phDbgMod, const char *pszName, RTUINTPTR cbSeg, uint32_t fFlags);
654
655	RTDECL(int) RTDbgModCreateDeferred(PRTDBGMOD phDbgMod, const char pszFilename, const char pszName, RTUINTPTR cb, uint32_t fFlags);
656	RTDECL(int) RTDbgModCreateFromImage(PRTDBGMOD phDbgMod, const char pszFilename, const char pszName, uint32_t fFlags);
657	RTDECL(int) RTDbgModCreateFromMap(PRTDBGMOD phDbgMod, const char pszFilename, const char pszName, RTUINTPTR uSubtrahend, uint32_t fFlags);
658
659
660	/**
661	* Retains another reference to the module.
662	*
663	* @returns New reference count, UINT32_MAX on invalid handle (asserted).
664	*
665	* @param hDbgMod The module handle.
666	*
667	* @remarks Will not take any locks.
668	*/
669	RTDECL(uint32_t) RTDbgModRetain(RTDBGMOD hDbgMod);
670
671	/**
672	* Release a reference to the module.
673	*
674	* When the reference count reaches zero, the module is destroyed.
675	*
676	* @returns New reference count, UINT32_MAX on invalid handle (asserted).
677	*
678	* @param hDbgMod The module handle. The NIL handle is quietly ignored
679	* and 0 is returned.
680	*
681	* @remarks Will not take any locks.
682	*/
683	RTDECL(uint32_t) RTDbgModRelease(RTDBGMOD hDbgMod);
684
685	/**
686	* Gets the module name.
687	*
688	* @returns Pointer to a read only string containing the name.
689	*
690	* @param hDbgMod The module handle.
691	*/
692	RTDECL(const char *) RTDbgModName(RTDBGMOD hDbgMod);
693
694	/**
695	* Converts an image relative address to a segment:offset address.
696	*
697	* @returns Segment index on success.
698	* NIL_RTDBGSEGIDX is returned if the module handle or the RVA are
699	* invalid.
700	*
701	* @param hDbgMod The module handle.
702	* @param uRva The image relative address to convert.
703	* @param poffSeg Where to return the segment offset. Optional.
704	*/
705	RTDECL(RTDBGSEGIDX) RTDbgModRvaToSegOff(RTDBGMOD hDbgMod, RTUINTPTR uRva, PRTUINTPTR poffSeg);
706
707	/**
708	* Image size when mapped if segments are mapped adjacently.
709	*
710	* For ELF, PE, and Mach-O images this is (usually) a natural query, for LX and
711	* NE and such it's a bit odder and the answer may not make much sense for them.
712	*
713	* @returns Image mapped size.
714	* RTUINTPTR_MAX is returned if the handle is invalid.
715	*
716	* @param hDbgMod The module handle.
717	*/
718	RTDECL(RTUINTPTR) RTDbgModImageSize(RTDBGMOD hDbgMod);
719
720	/**
721	* Gets the module tag value if any.
722	*
723	* @returns The tag. 0 if hDbgMod is invalid.
724	*
725	* @param hDbgMod The module handle.
726	*/
727	RTDECL(uint64_t) RTDbgModGetTag(RTDBGMOD hDbgMod);
728
729	/**
730	* Tags or untags the module.
731	*
732	* @returns IPRT status code.
733	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
734	*
735	* @param hDbgMod The module handle.
736	* @param uTag The tag value. The convention is that 0 is no tag
737	* and any other value means it's tagged. It's adviced
738	* to use some kind of unique number like an address
739	* (global or string cache for instance) to avoid
740	* collisions with other users
741	*/
742	RTDECL(int) RTDbgModSetTag(RTDBGMOD hDbgMod, uint64_t uTag);
743
744
745	/**
746	* Adds a segment to the module. Optional feature.
747	*
748	* This method is intended used for manually constructing debug info for a
749	* module. The main usage is from other debug info interpreters that want to
750	* avoid writing a debug info database and instead uses the standard container
751	* behind the scenes.
752	*
753	* @returns IPRT status code.
754	* @retval VERR_NOT_SUPPORTED if this feature isn't support by the debug info
755	* interpreter. This is a common return code.
756	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
757	* @retval VERR_DBG_ADDRESS_WRAP if uRva+cb wraps around.
758	* @retval VERR_DBG_SEGMENT_NAME_OUT_OF_RANGE if pszName is too short or long.
759	* @retval VERR_INVALID_PARAMETER if fFlags contains undefined flags.
760	* @retval VERR_DBG_SPECIAL_SEGMENT if *piSeg is a special segment.
761	* @retval VERR_DBG_INVALID_SEGMENT_INDEX if *piSeg doesn't meet expectations.
762	*
763	* @param hDbgMod The module handle.
764	* @param uRva The image relative address of the segment.
765	* @param cb The size of the segment.
766	* @param pszName The segment name. Does not normally need to be
767	* unique, although this is somewhat up to the
768	* debug interpreter to decide.
769	* @param fFlags Segment flags. Reserved for future used, MBZ.
770	* @param piSeg The segment index or NIL_RTDBGSEGIDX on input.
771	* The assigned segment index on successful return.
772	* Optional.
773	*/
774	RTDECL(int) RTDbgModSegmentAdd(RTDBGMOD hDbgMod, RTUINTPTR uRva, RTUINTPTR cb, const char *pszName,
775	uint32_t fFlags, PRTDBGSEGIDX piSeg);
776
777	/**
778	* Gets the number of segments in the module.
779	*
780	* This is can be used to determine the range which can be passed to
781	* RTDbgModSegmentByIndex and derivates.
782	*
783	* @returns The segment relative address.
784	* NIL_RTDBGSEGIDX if the handle is invalid.
785	*
786	* @param hDbgMod The module handle.
787	*/
788	RTDECL(RTDBGSEGIDX) RTDbgModSegmentCount(RTDBGMOD hDbgMod);
789
790	/**
791	* Query information about a segment.
792	*
793	* This can be used together with RTDbgModSegmentCount to enumerate segments.
794	* The index starts a 0 and stops one below RTDbgModSegmentCount.
795	*
796	* @returns IPRT status code.
797	* @retval VERR_DBG_INVALID_SEGMENT_INDEX if iSeg is too high.
798	* @retval VERR_DBG_SPECIAL_SEGMENT if iSeg indicates a special segment.
799	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
800	*
801	* @param hDbgMod The module handle.
802	* @param iSeg The segment index. No special segments.
803	* @param pSegInfo Where to return the segment info. The
804	* RTDBGSEGMENT::Address member will be set to
805	* RTUINTPTR_MAX or the load address used at link time.
806	*/
807	RTDECL(int) RTDbgModSegmentByIndex(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, PRTDBGSEGMENT pSegInfo);
808
809	/**
810	* Gets the size of a segment.
811	*
812	* This is a just a wrapper around RTDbgModSegmentByIndex.
813	*
814	* @returns The segment size.
815	* RTUINTPTR_MAX is returned if either the handle and segment index are
816	* invalid.
817	*
818	* @param hDbgMod The module handle.
819	* @param iSeg The segment index. RTDBGSEGIDX_ABS is not allowed.
820	* If RTDBGSEGIDX_RVA is used, the functions returns
821	* the same value as RTDbgModImageSize.
822	*/
823	RTDECL(RTUINTPTR) RTDbgModSegmentSize(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg);
824
825	/**
826	* Gets the image relative address of a segment.
827	*
828	* This is a just a wrapper around RTDbgModSegmentByIndex.
829	*
830	* @returns The segment relative address.
831	* RTUINTPTR_MAX is returned if either the handle and segment index are
832	* invalid.
833	*
834	* @param hDbgMod The module handle.
835	* @param iSeg The segment index. No special segment indexes
836	* allowed (asserted).
837	*/
838	RTDECL(RTUINTPTR) RTDbgModSegmentRva(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg);
839
840
841	/**
842	* Adds a line number to the module.
843	*
844	* @returns IPRT status code.
845	* @retval VERR_NOT_SUPPORTED if the module interpret doesn't support adding
846	* custom symbols. This is a common place occurrence.
847	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
848	* @retval VERR_DBG_SYMBOL_NAME_OUT_OF_RANGE if the symbol name is too long or
849	* short.
850	* @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
851	* it's not inside any of the segments defined by the module.
852	* @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
853	* @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
854	* end of the segment.
855	* @retval VERR_DBG_ADDRESS_WRAP if off+cb wraps around.
856	* @retval VERR_INVALID_PARAMETER if the symbol flags sets undefined bits.
857	*
858	* @param hDbgMod The module handle.
859	* @param pszSymbol The symbol name.
860	* @param iSeg The segment index.
861	* @param off The segment offset.
862	* @param cb The size of the symbol. Can be zero, although this
863	* may depend somewhat on the debug interpreter.
864	* @param fFlags Symbol flags. Reserved for the future, MBZ.
865	* @param piOrdinal Where to return the symbol ordinal on success. If
866	* the interpreter doesn't do ordinals, this will be set to
867	* UINT32_MAX. Optional.
868	*/
869	RTDECL(int) RTDbgModSymbolAdd(RTDBGMOD hDbgMod, const char *pszSymbol, RTDBGSEGIDX iSeg, RTUINTPTR off,
870	RTUINTPTR cb, uint32_t fFlags, uint32_t *piOrdinal);
871
872	/**
873	* Gets the symbol count.
874	*
875	* This can be used together wtih RTDbgModSymbolByOrdinal or
876	* RTDbgModSymbolByOrdinalA to enumerate all the symbols.
877	*
878	* @returns The number of symbols in the module.
879	* UINT32_MAX is returned if the module handle is invalid or some other
880	* error occurs.
881	*
882	* @param hDbgMod The module handle.
883	*/
884	RTDECL(uint32_t) RTDbgModSymbolCount(RTDBGMOD hDbgMod);
885
886	/**
887	* Queries symbol information by ordinal number.
888	*
889	* @returns IPRT status code.
890	* @retval VERR_SYMBOL_NOT_FOUND if there is no symbol at the given number.
891	* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
892	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
893	* @retval VERR_NOT_SUPPORTED if lookup by ordinal is not supported.
894	*
895	* @param hDbgMod The module handle.
896	* @param iOrdinal The symbol ordinal number. 0-based. The highest
897	* number is RTDbgModSymbolCount() - 1.
898	* @param pSymInfo Where to store the symbol information.
899	*/
900	RTDECL(int) RTDbgModSymbolByOrdinal(RTDBGMOD hDbgMod, uint32_t iOrdinal, PRTDBGSYMBOL pSymInfo);
901
902	/**
903	* Queries symbol information by ordinal number.
904	*
905	* @returns IPRT status code.
906	* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
907	* @retval VERR_NOT_SUPPORTED if lookup by ordinal is not supported.
908	* @retval VERR_SYMBOL_NOT_FOUND if there is no symbol at the given number.
909	* @retval VERR_NO_MEMORY if RTDbgSymbolAlloc fails.
910	*
911	* @param hDbgMod The module handle.
912	* @param iOrdinal The symbol ordinal number. 0-based. The highest
913	* number is RTDbgModSymbolCount() - 1.
914	* @param ppSymInfo Where to store the pointer to the returned
915	* symbol information. Always set. Free with
916	* RTDbgSymbolFree.
917	*/
918	RTDECL(int) RTDbgModSymbolByOrdinalA(RTDBGMOD hDbgMod, uint32_t iOrdinal, PRTDBGSYMBOL *ppSymInfo);
919
920	/**
921	* Queries symbol information by address.
922	*
923	* The returned symbol is what the debug info interpreter considers the symbol
924	* most applicable to the specified address. This usually means a symbol with an
925	* address equal or lower than the requested.
926	*
927	* @returns IPRT status code.
928	* @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
929	* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
930	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
931	* @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
932	* it's not inside any of the segments defined by the module.
933	* @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
934	* @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
935	* end of the segment.
936	*
937	* @param hDbgMod The module handle.
938	* @param iSeg The segment number.
939	* @param off The offset into the segment.
940	* @param poffDisp Where to store the distance between the
941	* specified address and the returned symbol.
942	* Optional.
943	* @param pSymInfo Where to store the symbol information.
944	*/
945	RTDECL(int) RTDbgModSymbolByAddr(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, PRTINTPTR poffDisp, PRTDBGSYMBOL pSymInfo);
946
947	/**
948	* Queries symbol information by address.
949	*
950	* The returned symbol is what the debug info interpreter considers the symbol
951	* most applicable to the specified address. This usually means a symbol with an
952	* address equal or lower than the requested.
953	*
954	* @returns IPRT status code.
955	* @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
956	* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
957	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
958	* @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
959	* it's not inside any of the segments defined by the module.
960	* @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
961	* @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
962	* end of the segment.
963	* @retval VERR_NO_MEMORY if RTDbgSymbolAlloc fails.
964	*
965	* @param hDbgMod The module handle.
966	* @param iSeg The segment index.
967	* @param off The offset into the segment.
968	* @param poffDisp Where to store the distance between the
969	* specified address and the returned symbol. Optional.
970	* @param ppSymInfo Where to store the pointer to the returned
971	* symbol information. Always set. Free with
972	* RTDbgSymbolFree.
973	*/
974	RTDECL(int) RTDbgModSymbolByAddrA(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, PRTINTPTR poffDisp, PRTDBGSYMBOL *ppSymInfo);
975
976	/**
977	* Queries symbol information by symbol name.
978	*
979	* @returns IPRT status code.
980	* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
981	* @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
982	* @retval VERR_DBG_SYMBOL_NAME_OUT_OF_RANGE if the symbol name is too long or
983	* short.
984	*
985	* @param hDbgMod The module handle.
986	* @param pszSymbol The symbol name.
987	* @param pSymInfo Where to store the symbol information.
988	*/
989	RTDECL(int) RTDbgModSymbolByName(RTDBGMOD hDbgMod, const char *pszSymbol, PRTDBGSYMBOL pSymInfo);
990
991	/**
992	* Queries symbol information by symbol name.
993	*
994	* @returns IPRT status code.
995	* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
996	* @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
997	* @retval VERR_DBG_SYMBOL_NAME_OUT_OF_RANGE if the symbol name is too long or
998	* short.
999	* @retval VERR_NO_MEMORY if RTDbgSymbolAlloc fails.
1000	*
1001	* @param hDbgMod The module handle.
1002	* @param pszSymbol The symbol name.
1003	* @param ppSymInfo Where to store the pointer to the returned
1004	* symbol information. Always set. Free with
1005	* RTDbgSymbolFree.
1006	*/
1007	RTDECL(int) RTDbgModSymbolByNameA(RTDBGMOD hDbgMod, const char pszSymbol, PRTDBGSYMBOL ppSymInfo);
1008
1009	/**
1010	* Adds a line number to the module.
1011	*
1012	* @returns IPRT status code.
1013	* @retval VERR_NOT_SUPPORTED if the module interpret doesn't support adding
1014	* custom symbols. This should be consider a normal response.
1015	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1016	* @retval VERR_DBG_FILE_NAME_OUT_OF_RANGE if the file name is too longer or
1017	* empty.
1018	* @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
1019	* it's not inside any of the segments defined by the module.
1020	* @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
1021	* @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
1022	* end of the segment.
1023	* @retval VERR_INVALID_PARAMETER if the line number flags sets undefined bits.
1024	*
1025	* @param hDbgMod The module handle.
1026	* @param pszFile The file name.
1027	* @param uLineNo The line number.
1028	* @param iSeg The segment index.
1029	* @param off The segment offset.
1030	* @param piOrdinal Where to return the line number ordinal on
1031	* success. If the interpreter doesn't do ordinals,
1032	* this will be set to UINT32_MAX. Optional.
1033	*/
1034	RTDECL(int) RTDbgModLineAdd(RTDBGMOD hDbgMod, const char *pszFile, uint32_t uLineNo,
1035	RTDBGSEGIDX iSeg, RTUINTPTR off, uint32_t *piOrdinal);
1036
1037	/**
1038	* Gets the line number count.
1039	*
1040	* This can be used together wtih RTDbgModLineByOrdinal or RTDbgModSymbolByLineA
1041	* to enumerate all the line number information.
1042	*
1043	* @returns The number of line numbers in the module.
1044	* UINT32_MAX is returned if the module handle is invalid or some other
1045	* error occurs.
1046	*
1047	* @param hDbgMod The module handle.
1048	*/
1049	RTDECL(uint32_t) RTDbgModLineCount(RTDBGMOD hDbgMod);
1050
1051	/**
1052	* Queries line number information by ordinal number.
1053	*
1054	* This can be used to enumerate the line numbers for the module. Use
1055	* RTDbgModLineCount() to figure the end of the ordinals.
1056	*
1057	* @returns IPRT status code.
1058	* @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
1059	* @retval VERR_DBG_LINE_NOT_FOUND if there is no line number with that
1060	* ordinal.
1061	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1062
1063	* @param hDbgMod The module handle.
1064	* @param iOrdinal The line number ordinal number.
1065	* @param pLineInfo Where to store the information about the line
1066	* number.
1067	*/
1068	RTDECL(int) RTDbgModLineByOrdinal(RTDBGMOD hDbgMod, uint32_t iOrdinal, PRTDBGLINE pLineInfo);
1069
1070	/**
1071	* Queries line number information by ordinal number.
1072	*
1073	* This can be used to enumerate the line numbers for the module. Use
1074	* RTDbgModLineCount() to figure the end of the ordinals.
1075	*
1076	* @returns IPRT status code.
1077	* @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
1078	* @retval VERR_DBG_LINE_NOT_FOUND if there is no line number with that
1079	* ordinal.
1080	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1081	* @retval VERR_NO_MEMORY if RTDbgLineAlloc fails.
1082	*
1083	* @param hDbgMod The module handle.
1084	* @param iOrdinal The line number ordinal number.
1085	* @param ppLineInfo Where to store the pointer to the returned line
1086	* number information. Always set. Free with
1087	* RTDbgLineFree.
1088	*/
1089	RTDECL(int) RTDbgModLineByOrdinalA(RTDBGMOD hDbgMod, uint32_t iOrdinal, PRTDBGLINE *ppLineInfo);
1090
1091	/**
1092	* Queries line number information by address.
1093	*
1094	* The returned line number is what the debug info interpreter considers the
1095	* one most applicable to the specified address. This usually means a line
1096	* number with an address equal or lower than the requested.
1097	*
1098	* @returns IPRT status code.
1099	* @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
1100	* @retval VERR_DBG_LINE_NOT_FOUND if no suitable line number was found.
1101	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1102	* @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
1103	* it's not inside any of the segments defined by the module.
1104	* @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
1105	* @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
1106	* end of the segment.
1107	*
1108	* @param hDbgMod The module handle.
1109	* @param iSeg The segment number.
1110	* @param off The offset into the segment.
1111	* @param poffDisp Where to store the distance between the
1112	* specified address and the returned symbol.
1113	* Optional.
1114	* @param pLineInfo Where to store the line number information.
1115	*/
1116	RTDECL(int) RTDbgModLineByAddr(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, PRTINTPTR poffDisp, PRTDBGLINE pLineInfo);
1117
1118	/**
1119	* Queries line number information by address.
1120	*
1121	* The returned line number is what the debug info interpreter considers the
1122	* one most applicable to the specified address. This usually means a line
1123	* number with an address equal or lower than the requested.
1124	*
1125	* @returns IPRT status code.
1126	* @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
1127	* @retval VERR_DBG_LINE_NOT_FOUND if no suitable line number was found.
1128	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1129	* @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
1130	* it's not inside any of the segments defined by the module.
1131	* @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
1132	* @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
1133	* end of the segment.
1134	* @retval VERR_NO_MEMORY if RTDbgLineAlloc fails.
1135	*
1136	* @param hDbgMod The module handle.
1137	* @param iSeg The segment number.
1138	* @param off The offset into the segment.
1139	* @param poffDisp Where to store the distance between the
1140	* specified address and the returned symbol.
1141	* Optional.
1142	* @param ppLineInfo Where to store the pointer to the returned line
1143	* number information. Always set. Free with
1144	* RTDbgLineFree.
1145	*/
1146	RTDECL(int) RTDbgModLineByAddrA(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, PRTINTPTR poffDisp, PRTDBGLINE *ppLineInfo);
1147	/** @} */
1148
1149	/** @} */
1150
1151	RT_C_DECLS_END
1152
1153	#endif
1154

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

source: vbox/trunk/include/iprt/dbg.h@ 40451

Download in other formats: