Linux and UNIX Man Pages

Linux & Unix Commands - Search Man Pages

FreeBSD 11.0 - man page for dwarf_get_macro_details (freebsd section 3)

DWARF_GET_MACRO_DETAILS(3)				   BSD 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 informa- tion 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 informa- tion 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)
BSD
March 20, 2011 BSD