FreeBSD manual
download PDF document: dwarf_get_macro_details.3.pdf
DWARF_GET_MACRO_DETAILS(3) FreeBSD Library Functions Manual
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
and sets the argument err.
EXAMPLES
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;
}
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.
SEE ALSO
dwarf(3), dwarf_dealloc(3), dwarf_find_macro_value_start(3),
dwarf_init(3)
FreeBSD 14.0-RELEASE-p11 March 20, 2011 FreeBSD 14.0-RELEASE-p11