Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.

DWARF_GET_MACRO_DETAILS(3)                            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
     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.

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)

NetBSD 10.99                    March 20, 2011                    NetBSD 10.99