dbg.h@ 32060

Last change on this file since 32060 was 28800, checked in by vboxsync, 15 years ago
Automated rebranding to Oracle copyright/license strings via filemuncher
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 44.5 KB

Line
1	/* $Id: dbg.h 28800 2010-04-27 08:22:32Z 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 ment. (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	* Query a line number by address.
598	*
599	* @returns IPRT status code. See RTDbgModSymbolAddrA for more specific ones.
600	* @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
601	* @retval VERR_NOT_FOUND if the address couldn't be mapped to a module.
602	*
603	* @param hDbgAs The address space handle.
604	* @param Addr The address which closest symbol is requested.
605	* @param poffDisp Where to return the distance between the line
606	* number and address.
607	* @param ppLine Where to return the pointer to the allocated line
608	* number info. Always set. Free with RTDbgLineFree.
609	*/
610	RTDECL(int) RTDbgAsLineByAddrA(RTDBGAS hDbgAs, RTUINTPTR Addr, PRTINTPTR poffDisp, PRTDBGLINE *ppLine);
611
612	/** @todo Missing some bits here. */
613
614	/** @} */
615
616
617	/** @defgroup grp_rt_dbgmod RTDbgMod - Debug Module Interpreter
618	* @{
619	*/
620
621	/**
622	* Creates a module based on the default debug info container.
623	*
624	* This can be used to manually load a module and its symbol. The primary user
625	* group is the debug info interpreters, which use this API to create an
626	* efficient debug info container behind the scenes and forward all queries to
627	* it once the info has been loaded.
628	*
629	* @returns IPRT status code.
630	*
631	* @param phDbgMod Where to return the module handle.
632	* @param pszName The name of the module (mandatory).
633	* @param cbSeg The size of initial segment. If zero, segments will
634	* have to be added manually using RTDbgModSegmentAdd.
635	* @param fFlags Flags reserved for future extensions, MBZ for now.
636	*/
637	RTDECL(int) RTDbgModCreate(PRTDBGMOD phDbgMod, const char *pszName, RTUINTPTR cbSeg, uint32_t fFlags);
638
639	RTDECL(int) RTDbgModCreateDeferred(PRTDBGMOD phDbgMod, const char pszFilename, const char pszName, RTUINTPTR cb, uint32_t fFlags);
640	RTDECL(int) RTDbgModCreateFromImage(PRTDBGMOD phDbgMod, const char pszFilename, const char pszName, uint32_t fFlags);
641	RTDECL(int) RTDbgModCreateFromMap(PRTDBGMOD phDbgMod, const char pszFilename, const char pszName, RTUINTPTR uSubtrahend, uint32_t fFlags);
642
643
644	/**
645	* Retains another reference to the module.
646	*
647	* @returns New reference count, UINT32_MAX on invalid handle (asserted).
648	*
649	* @param hDbgMod The module handle.
650	*
651	* @remarks Will not take any locks.
652	*/
653	RTDECL(uint32_t) RTDbgModRetain(RTDBGMOD hDbgMod);
654
655	/**
656	* Release a reference to the module.
657	*
658	* When the reference count reaches zero, the module is destroyed.
659	*
660	* @returns New reference count, UINT32_MAX on invalid handle (asserted).
661	*
662	* @param hDbgMod The module handle. The NIL handle is quietly ignored
663	* and 0 is returned.
664	*
665	* @remarks Will not take any locks.
666	*/
667	RTDECL(uint32_t) RTDbgModRelease(RTDBGMOD hDbgMod);
668
669	/**
670	* Gets the module name.
671	*
672	* @returns Pointer to a read only string containing the name.
673	*
674	* @param hDbgMod The module handle.
675	*/
676	RTDECL(const char *) RTDbgModName(RTDBGMOD hDbgMod);
677
678	/**
679	* Converts an image relative address to a segment:offset address.
680	*
681	* @returns Segment index on success.
682	* NIL_RTDBGSEGIDX is returned if the module handle or the RVA are
683	* invalid.
684	*
685	* @param hDbgMod The module handle.
686	* @param uRva The image relative address to convert.
687	* @param poffSeg Where to return the segment offset. Optional.
688	*/
689	RTDECL(RTDBGSEGIDX) RTDbgModRvaToSegOff(RTDBGMOD hDbgMod, RTUINTPTR uRva, PRTUINTPTR poffSeg);
690
691	/**
692	* Image size when mapped if segments are mapped adjecently.
693	*
694	* For ELF, PE, and Mach-O images this is (usually) a natural query, for LX and
695	* NE and such it's a bit odder and the answer may not make much sense for them.
696	*
697	* @returns Image mapped size.
698	* RTUINTPTR_MAX is returned if the handle is invalid.
699	*
700	* @param hDbgMod The module handle.
701	*/
702	RTDECL(RTUINTPTR) RTDbgModImageSize(RTDBGMOD hDbgMod);
703
704	/**
705	* Gets the module tag value if any.
706	*
707	* @returns The tag. 0 if hDbgMod is invalid.
708	*
709	* @param hDbgMod The module handle.
710	*/
711	RTDECL(uint64_t) RTDbgModGetTag(RTDBGMOD hDbgMod);
712
713	/**
714	* Tags or untags the module.
715	*
716	* @returns IPRT status code.
717	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
718	*
719	* @param hDbgMod The module handle.
720	* @param uTag The tag value. The convention is that 0 is no tag
721	* and any other value means it's tagged. It's adviced
722	* to use some kind of unique number like an address
723	* (global or string cache for instance) to avoid
724	* collisions with other users
725	*/
726	RTDECL(int) RTDbgModSetTag(RTDBGMOD hDbgMod, uint64_t uTag);
727
728
729	/**
730	* Adds a segment to the module. Optional feature.
731	*
732	* This method is intended used for manually constructing debug info for a
733	* module. The main usage is from other debug info interpreters that want to
734	* avoid writing a debug info database and instead uses the standard container
735	* behind the scenes.
736	*
737	* @returns IPRT status code.
738	* @retval VERR_NOT_SUPPORTED if this feature isn't support by the debug info
739	* interpreter. This is a common return code.
740	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
741	* @retval VERR_DBG_ADDRESS_WRAP if uRva+cb wraps around.
742	* @retval VERR_DBG_SEGMENT_NAME_OUT_OF_RANGE if pszName is too short or long.
743	* @retval VERR_INVALID_PARAMETER if fFlags contains undefined flags.
744	* @retval VERR_DBG_SPECIAL_SEGMENT if *piSeg is a special segment.
745	* @retval VERR_DBG_INVALID_SEGMENT_INDEX if *piSeg doesn't meet expectations.
746	*
747	* @param hDbgMod The module handle.
748	* @param uRva The image relative address of the segment.
749	* @param cb The size of the segment.
750	* @param pszName The segment name. Does not normally need to be
751	* unique, although this is somewhat up to the
752	* debug interpreter to decide.
753	* @param fFlags Segment flags. Reserved for future used, MBZ.
754	* @param piSeg The segment index or NIL_RTDBGSEGIDX on input.
755	* The assigned segment index on successful return.
756	* Optional.
757	*/
758	RTDECL(int) RTDbgModSegmentAdd(RTDBGMOD hDbgMod, RTUINTPTR uRva, RTUINTPTR cb, const char *pszName,
759	uint32_t fFlags, PRTDBGSEGIDX piSeg);
760
761	/**
762	* Gets the number of segments in the module.
763	*
764	* This is can be used to determin the range which can be passed to
765	* RTDbgModSegmentByIndex and derivates.
766	*
767	* @returns The segment relative address.
768	* NIL_RTDBGSEGIDX if the handle is invalid.
769	*
770	* @param hDbgMod The module handle.
771	*/
772	RTDECL(RTDBGSEGIDX) RTDbgModSegmentCount(RTDBGMOD hDbgMod);
773
774	/**
775	* Query information about a segment.
776	*
777	* This can be used together with RTDbgModSegmentCount to enumerate segments.
778	* The index starts a 0 and stops one below RTDbgModSegmentCount.
779	*
780	* @returns IPRT status code.
781	* @retval VERR_DBG_INVALID_SEGMENT_INDEX if iSeg is too high.
782	* @retval VERR_DBG_SPECIAL_SEGMENT if iSeg indicates a special segment.
783	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
784	*
785	* @param hDbgMod The module handle.
786	* @param iSeg The segment index. No special segments.
787	* @param pSegInfo Where to return the segment info. The
788	* RTDBGSEGMENT::Address member will be set to
789	* RTUINTPTR_MAX or the load address used at link time.
790	*/
791	RTDECL(int) RTDbgModSegmentByIndex(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, PRTDBGSEGMENT pSegInfo);
792
793	/**
794	* Gets the size of a segment.
795	*
796	* This is a just a wrapper around RTDbgModSegmentByIndex.
797	*
798	* @returns The segment size.
799	* RTUINTPTR_MAX is returned if either the handle and segment index are
800	* invalid.
801	*
802	* @param hDbgMod The module handle.
803	* @param iSeg The segment index. RTDBGSEGIDX_ABS is not allowed.
804	* If RTDBGSEGIDX_RVA is used, the functions returns
805	* the same value as RTDbgModImageSize.
806	*/
807	RTDECL(RTUINTPTR) RTDbgModSegmentSize(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg);
808
809	/**
810	* Gets the image relative address of a segment.
811	*
812	* This is a just a wrapper around RTDbgModSegmentByIndex.
813	*
814	* @returns The segment relative address.
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. No special segment indexes
820	* allowed (asserted).
821	*/
822	RTDECL(RTUINTPTR) RTDbgModSegmentRva(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg);
823
824
825	/**
826	* Adds a line number to the module.
827	*
828	* @returns IPRT status code.
829	* @retval VERR_NOT_SUPPORTED if the module interpret doesn't support adding
830	* custom symbols. This is a common place occurance.
831	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
832	* @retval VERR_DBG_SYMBOL_NAME_OUT_OF_RANGE if the symbol name is too long or
833	* short.
834	* @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
835	* it's not inside any of the segments defined by the module.
836	* @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
837	* @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
838	* end of the segment.
839	* @retval VERR_DBG_ADDRESS_WRAP if off+cb wraps around.
840	* @retval VERR_INVALID_PARAMETER if the symbol flags sets undefined bits.
841	*
842	* @param hDbgMod The module handle.
843	* @param pszSymbol The symbol name.
844	* @param iSeg The segment index.
845	* @param off The segment offset.
846	* @param cb The size of the symbol. Can be zero, although this
847	* may depend somewhat on the debug interpreter.
848	* @param fFlags Symbol flags. Reserved for the future, MBZ.
849	* @param piOrdinal Where to return the symbol ordinal on success. If
850	* the interpreter doesn't do ordinals, this will be set to
851	* UINT32_MAX. Optional.
852	*/
853	RTDECL(int) RTDbgModSymbolAdd(RTDBGMOD hDbgMod, const char *pszSymbol, RTDBGSEGIDX iSeg, RTUINTPTR off,
854	RTUINTPTR cb, uint32_t fFlags, uint32_t *piOrdinal);
855
856	/**
857	* Gets the symbol count.
858	*
859	* This can be used together wtih RTDbgModSymbolByOrdinal or
860	* RTDbgModSymbolByOrdinalA to enumerate all the symbols.
861	*
862	* @returns The number of symbols in the module.
863	* UINT32_MAX is returned if the module handle is invalid or some other
864	* error occurs.
865	*
866	* @param hDbgMod The module handle.
867	*/
868	RTDECL(uint32_t) RTDbgModSymbolCount(RTDBGMOD hDbgMod);
869
870	/**
871	* Queries symbol information by ordinal number.
872	*
873	* @returns IPRT status code.
874	* @retval VERR_SYMBOL_NOT_FOUND if there is no symbol at the given number.
875	* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
876	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
877	* @retval VERR_NOT_SUPPORTED if lookup by ordinal is not supported.
878	*
879	* @param hDbgMod The module handle.
880	* @param iOrdinal The symbol ordinal number. 0-based. The highest
881	* number is RTDbgModSymbolCount() - 1.
882	* @param pSymInfo Where to store the symbol information.
883	*/
884	RTDECL(int) RTDbgModSymbolByOrdinal(RTDBGMOD hDbgMod, uint32_t iOrdinal, PRTDBGSYMBOL pSymInfo);
885
886	/**
887	* Queries symbol information by ordinal number.
888	*
889	* @returns IPRT status code.
890	* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
891	* @retval VERR_NOT_SUPPORTED if lookup by ordinal is not supported.
892	* @retval VERR_SYMBOL_NOT_FOUND if there is no symbol at the given number.
893	* @retval VERR_NO_MEMORY if RTDbgSymbolAlloc fails.
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 ppSymInfo Where to store the pointer to the returned
899	* symbol information. Always set. Free with
900	* RTDbgSymbolFree.
901	*/
902	RTDECL(int) RTDbgModSymbolByOrdinalA(RTDBGMOD hDbgMod, uint32_t iOrdinal, PRTDBGSYMBOL *ppSymInfo);
903
904	/**
905	* Queries symbol information by address.
906	*
907	* The returned symbol is what the debug info interpreter consideres the symbol
908	* most applicable to the specified address. This usually means a symbol with an
909	* address equal or lower than the requested.
910	*
911	* @returns IPRT status code.
912	* @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
913	* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
914	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
915	* @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
916	* it's not inside any of the segments defined by the module.
917	* @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
918	* @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
919	* end of the segment.
920	*
921	* @param hDbgMod The module handle.
922	* @param iSeg The segment number.
923	* @param off The offset into the segment.
924	* @param poffDisp Where to store the distance between the
925	* specified address and the returned symbol.
926	* Optional.
927	* @param pSymInfo Where to store the symbol information.
928	*/
929	RTDECL(int) RTDbgModSymbolByAddr(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, PRTINTPTR poffDisp, PRTDBGSYMBOL pSymInfo);
930
931	/**
932	* Queries symbol information by address.
933	*
934	* The returned symbol is what the debug info interpreter consideres the symbol
935	* most applicable to the specified address. This usually means a symbol with an
936	* address equal or lower than the requested.
937	*
938	* @returns IPRT status code.
939	* @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
940	* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
941	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
942	* @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
943	* it's not inside any of the segments defined by the module.
944	* @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
945	* @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
946	* end of the segment.
947	* @retval VERR_NO_MEMORY if RTDbgSymbolAlloc fails.
948	*
949	* @param hDbgMod The module handle.
950	* @param iSeg The segment index.
951	* @param off The offset into the segment.
952	* @param poffDisp Where to store the distance between the
953	* specified address and the returned symbol. Optional.
954	* @param ppSymInfo Where to store the pointer to the returned
955	* symbol information. Always set. Free with
956	* RTDbgSymbolFree.
957	*/
958	RTDECL(int) RTDbgModSymbolByAddrA(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, PRTINTPTR poffDisp, PRTDBGSYMBOL *ppSymInfo);
959
960	/**
961	* Queries symbol information by symbol name.
962	*
963	* @returns IPRT status code.
964	* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
965	* @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
966	* @retval VERR_DBG_SYMBOL_NAME_OUT_OF_RANGE if the symbol name is too long or
967	* short.
968	*
969	* @param hDbgMod The module handle.
970	* @param pszSymbol The symbol name.
971	* @param pSymInfo Where to store the symbol information.
972	*/
973	RTDECL(int) RTDbgModSymbolByName(RTDBGMOD hDbgMod, const char *pszSymbol, PRTDBGSYMBOL pSymInfo);
974
975	/**
976	* Queries symbol information by symbol name.
977	*
978	* @returns IPRT status code.
979	* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
980	* @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
981	* @retval VERR_DBG_SYMBOL_NAME_OUT_OF_RANGE if the symbol name is too long or
982	* short.
983	* @retval VERR_NO_MEMORY if RTDbgSymbolAlloc fails.
984	*
985	* @param hDbgMod The module handle.
986	* @param pszSymbol The symbol name.
987	* @param ppSymInfo Where to store the pointer to the returned
988	* symbol information. Always set. Free with
989	* RTDbgSymbolFree.
990	*/
991	RTDECL(int) RTDbgModSymbolByNameA(RTDBGMOD hDbgMod, const char pszSymbol, PRTDBGSYMBOL ppSymInfo);
992
993	/**
994	* Adds a line number to the module.
995	*
996	* @returns IPRT status code.
997	* @retval VERR_NOT_SUPPORTED if the module interpret doesn't support adding
998	* custom symbols. This should be consider a normal response.
999	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1000	* @retval VERR_DBG_FILE_NAME_OUT_OF_RANGE if the file name is too longer or
1001	* empty.
1002	* @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
1003	* it's not inside any of the segments defined by the module.
1004	* @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
1005	* @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
1006	* end of the segment.
1007	* @retval VERR_INVALID_PARAMETER if the line number flags sets undefined bits.
1008	*
1009	* @param hDbgMod The module handle.
1010	* @param pszFile The file name.
1011	* @param uLineNo The line number.
1012	* @param iSeg The segment index.
1013	* @param off The segment offset.
1014	* @param piOrdinal Where to return the line number ordinal on
1015	* success. If the interpreter doesn't do ordinals,
1016	* this will be set to UINT32_MAX. Optional.
1017	*/
1018	RTDECL(int) RTDbgModLineAdd(RTDBGMOD hDbgMod, const char *pszFile, uint32_t uLineNo,
1019	RTDBGSEGIDX iSeg, RTUINTPTR off, uint32_t *piOrdinal);
1020
1021	/**
1022	* Gets the line number count.
1023	*
1024	* This can be used together wtih RTDbgModLineByOrdinal or RTDbgModSymbolByLineA
1025	* to enumerate all the line number information.
1026	*
1027	* @returns The number of line numbers in the module.
1028	* UINT32_MAX is returned if the module handle is invalid or some other
1029	* error occurs.
1030	*
1031	* @param hDbgMod The module handle.
1032	*/
1033	RTDECL(uint32_t) RTDbgModLineCount(RTDBGMOD hDbgMod);
1034
1035	/**
1036	* Queries line number information by ordinal number.
1037	*
1038	* This can be used to enumerate the line numbers for the module. Use
1039	* RTDbgModLineCount() to figure the end of the ordinals.
1040	*
1041	* @returns IPRT status code.
1042	* @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
1043	* @retval VERR_DBG_LINE_NOT_FOUND if there is no line number with that
1044	* ordinal.
1045	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1046
1047	* @param hDbgMod The module handle.
1048	* @param iOrdinal The line number ordinal number.
1049	* @param pLineInfo Where to store the information about the line
1050	* number.
1051	*/
1052	RTDECL(int) RTDbgModLineByOrdinal(RTDBGMOD hDbgMod, uint32_t iOrdinal, PRTDBGLINE pLineInfo);
1053
1054	/**
1055	* Queries line number information by ordinal number.
1056	*
1057	* This can be used to enumerate the line numbers for the module. Use
1058	* RTDbgModLineCount() to figure the end of the ordinals.
1059	*
1060	* @returns IPRT status code.
1061	* @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
1062	* @retval VERR_DBG_LINE_NOT_FOUND if there is no line number with that
1063	* ordinal.
1064	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1065	* @retval VERR_NO_MEMORY if RTDbgLineAlloc fails.
1066	*
1067	* @param hDbgMod The module handle.
1068	* @param iOrdinal The line number ordinal number.
1069	* @param ppLineInfo Where to store the pointer to the returned line
1070	* number information. Always set. Free with
1071	* RTDbgLineFree.
1072	*/
1073	RTDECL(int) RTDbgModLineByOrdinalA(RTDBGMOD hDbgMod, uint32_t iOrdinal, PRTDBGLINE *ppLineInfo);
1074
1075	/**
1076	* Queries line number information by address.
1077	*
1078	* The returned line number is what the debug info interpreter consideres the
1079	* one most applicable to the specified address. This usually means a line
1080	* number with an address equal or lower than the requested.
1081	*
1082	* @returns IPRT status code.
1083	* @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
1084	* @retval VERR_DBG_LINE_NOT_FOUND if no suitable line number was found.
1085	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1086	* @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
1087	* it's not inside any of the segments defined by the module.
1088	* @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
1089	* @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
1090	* end of the segment.
1091	*
1092	* @param hDbgMod The module handle.
1093	* @param iSeg The segment number.
1094	* @param off The offset into the segment.
1095	* @param poffDisp Where to store the distance between the
1096	* specified address and the returned symbol.
1097	* Optional.
1098	* @param pLineInfo Where to store the line number information.
1099	*/
1100	RTDECL(int) RTDbgModLineByAddr(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, PRTINTPTR poffDisp, PRTDBGLINE pLineInfo);
1101
1102	/**
1103	* Queries line number information by address.
1104	*
1105	* The returned line number is what the debug info interpreter consideres the
1106	* one most applicable to the specified address. This usually means a line
1107	* number with an address equal or lower than the requested.
1108	*
1109	* @returns IPRT status code.
1110	* @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
1111	* @retval VERR_DBG_LINE_NOT_FOUND if no suitable line number was found.
1112	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1113	* @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
1114	* it's not inside any of the segments defined by the module.
1115	* @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
1116	* @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
1117	* end of the segment.
1118	* @retval VERR_NO_MEMORY if RTDbgLineAlloc fails.
1119	*
1120	* @param hDbgMod The module handle.
1121	* @param iSeg The segment number.
1122	* @param off The offset into the segment.
1123	* @param poffDisp Where to store the distance between the
1124	* specified address and the returned symbol.
1125	* Optional.
1126	* @param ppLineInfo Where to store the pointer to the returned line
1127	* number information. Always set. Free with
1128	* RTDbgLineFree.
1129	*/
1130	RTDECL(int) RTDbgModLineByAddrA(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, PRTINTPTR poffDisp, PRTDBGLINE *ppLineInfo);
1131	/** @} */
1132
1133	/** @} */
1134
1135	RT_C_DECLS_END
1136
1137	#endif
1138

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

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

Download in other formats: