dbg.h@ 26558

Last change on this file since 26558 was 25645, checked in by vboxsync, 15 years ago
IPRT,DoxyFile.Core: Mopped up the errors in the IPRT doxygen run.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 44.6 KB

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

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

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

Download in other formats: