1 .\" Copyright (c) 2011 Kai Wang
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25 .\" $Id: dwarf_get_macro_details.3 2071 2011-10-27 03:20:00Z jkoshy $
29 .Dt DWARF_GET_MACRO_DETAILS 3
31 .Nm dwarf_get_macro_details
32 .Nd retrieve macro information
38 .Fo dwarf_get_macro_details
40 .Fa "Dwarf_Off offset"
41 .Fa "Dwarf_Unsigned max_count"
42 .Fa "Dwarf_Signed *entry_cnt"
43 .Fa "Dwarf_Macro_Details **details"
44 .Fa "Dwarf_Error *err"
48 .Fn dwarf_get_macro_details
49 retrieves information about macros associated with a DWARF debug
51 Information about macro entries are returned as an array of
53 .Vt Dwarf_Macro_Details ,
55 .Vt Dwarf_Macro_Details
56 descriptor describing one macro information entry.
60 should reference a DWARF debug context allocated using
64 is an offset, relative to the
66 section, to the start of the desired macro information.
69 specifies the maximum number of macro information entries
70 to be returned, or 0 if all entries are to be returned.
73 should point to a location that will be set to the number
74 of entries actually returned.
77 should point to a location that will be set to a pointer to
79 .Vt Dwarf_Macro_Details
83 is not NULL, it will be used to store error information in case
86 .Vt Dwarf_Macro_Details
87 descriptors are defined in the header file
89 and consist of the following fields:
90 .Bl -tag -width ".Va dmd_fileindex" -compact
92 The section-relative offset within the
94 section of the macro information entry being described.
96 The type code of this macro information entry; one of the
98 constants defined by the DWARF specification.
100 The line number associated with the macro information
101 entry, or 0 if there is no applicable line number.
103 The source file index for the macro information entry.
104 This field is only meaningful when
107 .Dv DW_MACINFO_start_file .
109 The contents of this field is a pointer to a NUL-terminated string
110 whose meaning depends on the value of the
113 .Bl -tag -width ".Dv DW_MACINFO_vendor_ext" -compact
114 .It Dv DW_MACINFO_define
115 The returned string contains the macro name and value.
116 .It Dv DW_MACINFO_undef
117 The string holds the macro name.
118 .It Dv DW_MACINFO_vendor_ext
121 field points to a vendor defined string.
123 The field is NULL for other values of
126 .Ss Memory Management
127 The memory area used for the array of
128 .Vt Dwarf_Macro_Details
129 descriptors returned in argument
133 The application should not attempt to directly free this pointer.
134 Portable code should instead use
136 with the allocation type
138 to indicate that the memory may be freed.
141 .Fn dwarf_get_macro_details
147 if there is no more macro information at the specified offset
149 In case of an error, it returns
151 and sets the argument
155 .Fn dwarf_get_macro_details
157 .Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY"
158 .It Bq Er DW_DLE_ARGUMENT
165 .It Bq Er DW_DLE_NO_ENTRY
166 There is no more macro information at the specified offset
170 To loop through all the macro information entries associated with
171 a DWARF debug context:
172 .Bd -literal -offset indent
174 Dwarf_Unsigned offset;
176 Dwarf_Macro_Details *md;
180 while (dwarf_get_macro_details(dbg, offset, 0,
181 &cnt, &md, &de) == DW_DLV_OK) {
182 for (i = 0; i < cnt; i++) {
183 /* Access fields of md[i] ... */
185 offset = md[cnt - 1].dmd_offset + 1;
190 .Xr dwarf_dealloc 3 ,
191 .Xr dwarf_find_macro_value_start 3 ,