DWARF_GET_MACRO_DETAILS(3)

DWARF_GET_MACRO_DETAILS(3) | Library Functions Manual | DWARF_GET_MACRO_DETAILS(3)

# 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)

March 20, 2011 | NetBSD 9.0