NAME
dwarf_get_macro_details —
retrieve
macro information
LIBRARY
DWARF Access Library (libdwarf, -ldwarf)
SYNOPSIS
#include <libdwarf.h>
int
dwarf_get_macro_details(
Dwarf_Debug dbg,
Dwarf_Off offset,
Dwarf_Unsigned
max_count,
Dwarf_Signed *entry_cnt,
Dwarf_Macro_Details **details,
Dwarf_Error *err);
DESCRIPTION
Function
dwarf_get_macro_details() retrieves information about
macros associated with a DWARF debug context. Information about macro entries
are returned as an array of descriptors of type
Dwarf_Macro_Details, with each
Dwarf_Macro_Details descriptor describing one macro
information entry.
Argument
dbg should reference a DWARF debug context
allocated using
dwarf_init(3). Argument
offset is an offset, relative to the
“.debug_macinfo” section, to the start of the desired macro
information. Argument
max_count specifies the maximum
number of macro information entries to be returned, or 0 if all entries are to
be returned. Argument
entry_cnt should point to a
location that will be set to the number of entries actually returned. Argument
details should point to a location that will be set to a
pointer to an array of
Dwarf_Macro_Details descriptors.
If argument
err is not NULL, it will be used to store
error information in case of an error.
Dwarf_Macro_Details descriptors are defined in the header
file
<libdwarf.h>, and consist of
the following fields:
- dmd_offset
- The section-relative offset within the
“.debug_macinfo” section of the macro information entry being
described.
- dmd_type
- The type code of this macro information entry; one of the
DW_MACINFO_*
constants defined by the DWARF
specification.
- dmd_lineno
- The line number associated with the macro information
entry, or 0 if there is no applicable line number.
- dmd_fileindex
- The source file index for the macro information entry. This
field is only meaningful when dmd_type field is set
to
DW_MACINFO_start_file
.
- dmd_macro
- The contents of this field is a pointer to a NUL-terminated
string whose meaning depends on the value of the
dmd_type field:
DW_MACINFO_define
- The returned string contains the macro name and
value.
DW_MACINFO_undef
- The string holds the macro name.
DW_MACINFO_vendor_ext
- The dmd_macro field points to a
vendor defined string.
The field is NULL for other values of dmd_type.
Memory Management
The memory area used for the array of
Dwarf_Macro_Details
descriptors returned in argument
details is owned by the
DWARF Access Library (libdwarf, -ldwarf). The
application should not attempt to directly free this pointer. Portable code
should instead use
dwarf_dealloc() with the allocation type
DW_DLA_STRING
to indicate that the memory may be
freed.
RETURN VALUES
Function
dwarf_get_macro_details() returns
DW_DLV_OK
when it succeeds. It returns
DW_DLV_NO_ENTRY
if there is no more macro information
at the specified offset
offset. In case of an error, it
returns
DW_DLV_ERROR
and sets the argument
err.
ERRORS
Function
dwarf_get_macro_details() can fail with:
-
-
- [
DW_DLE_ARGUMENT
]
- One of the arguments dbg,
entry_cnt or details was
NULL.
-
-
- [
DW_DLE_NO_ENTRY
]
- There is no more macro information at the specified offset
offset.
EXAMPLE
To loop through all the macro information entries associated with a DWARF debug
context:
Dwarf_Debug dbg;
Dwarf_Unsigned offset;
Dwarf_Signed cnt;
Dwarf_Macro_Details *md;
Dwarf_Error de;
offset = 0;
while (dwarf_get_macro_details(dbg, offset, 0,
&cnt, &md, &de) == DW_DLV_OK) {
for (i = 0; i < cnt; i++) {
/* Access fields of md[i] ... */
}
offset = md[cnt - 1].dmd_offset + 1;
}
SEE ALSO
dwarf(3),
dwarf_dealloc(3),
dwarf_find_macro_value_start(3),
dwarf_init(3)