Manual browser: 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:

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:

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; 
}