Manual browser: dwarf_next_cu_header(3)

DWARF_NEXT_CU_HEADER(3)

Library Functions Manual

DWARF_NEXT_CU_HEADER(3)

NAME

dwarf_next_cu_header, dwarf_next_cu_header_b — step through compilation units in a DWARF debug context

LIBRARY

DWARF Access Library (libdwarf, -ldwarf)

SYNOPSIS

#include <libdwarf.h>

int
dwarf_next_cu_header(Dwarf_Debug dbg, Dwarf_Unsigned *cu_length, Dwarf_Half *cu_version, Dwarf_Off *cu_abbrev_offset, Dwarf_Half *cu_pointer_size, Dwarf_Unsigned *cu_next_offset, Dwarf_Error *err);

int
dwarf_next_cu_header_b(Dwarf_Debug dbg, Dwarf_Unsigned *cu_length, Dwarf_Half *cu_version, Dwarf_Off *cu_abbrev_offset, Dwarf_Half *cu_pointer_size, Dwarf_Half *cu_offset_size, Dwarf_Half *cu_extension_size, Dwarf_Unsigned *cu_next_offset, Dwarf_Error *err);

DESCRIPTION

These functions are used to step through compilation unit contexts associated with a DWARF debug context, optionally returning information about the unit.

Function dwarf_next_cu_header_b() is the API recommended for new application code. Argument dbg should reference a DWARF debug context allocated using dwarf_init(3). Argument cu_length should point to a location that will be set to the length of the compilation unit. Argument cu_version should point to a location that will be set to the version number for the compilation unit. Argument cu_abbrev_offset should point to a location that will be set to the starting offset (in the “.debug_abbrev” section) of the set of debugging information entry abbreviations associated with this compilation unit. Argument cu_pointer_size should point to a location that will be set to the size in bytes of an address for the machine architecture of the underlying object being debugged. Argument cu_offset_size should point to a location that will be set to the size in bytes for a DWARF offset in the compilation unit. Argument cu_extension_size is only needed for processing MIPS/IRIX objects that use a non-standard DWARF format. It should point to a location that will be set to 4 for normal objects and to 0 for non-standard ones. Argument cu_next_offset should point to a location that will be set to the offset of the next compilation unit header in the “.debug_info” section. Argument err should point to a location that will hold an error descriptor in case of an error.

Function dwarf_next_cu_header() is less general than dwarf_next_cu_header_b(), and is deprecated for use by new application code. Argument dbg should reference a DWARF debug context allocated using dwarf_init(3). Argument cu_length should point to a location that will be set to the length of the compilation unit. Argument cu_version should point to a location that will be set to the version number for the compilation unit. Argument cu_abbrev_offset should point to a location that will be set to the starting offset in the “.debug_abbrev” section of the set of debugging information entry abbreviations associated with this compilation unit. Argument cu_pointer_size should point to a location that will be set to the size of an address in bytes for the machine architecture of the underlying debugging object. Argument cu_next_offset should point to a location that will be set to the offset of the next compilation unit. Argument err should point to a location that will hold an error descriptor in case of an error.

A value of NULL may be used for any of the arguments cu_length, cu_version, cu_abbrev_offset, cu_pointer_size, cu_offset_size, cu_extension_size, cu_next_offset and err if the caller is not interested in the respective value.

Iterating Through Compilation Units in a Debug Context

The first call to functions dwarf_next_cu_header_b() and dwarf_next_cu_header() for a given debug context will return information about the first compilation unit in the debug context. Subsequent calls to these functions will iterate through the remaining compilation units in the debug context. On stepping past the last compilation unit in the debug context, functions dwarf_next_cu_header() and dwarf_next_cu_header_b() return DW_DLV_NO_ENTRY and reset their internal state. The next call to these functions will restart from the first compilation unit in the debug context.

RETURN VALUES

On success, these functions return DW_DLV_OK. In case of an error, they return DW_DLV_ERROR and set argument err. When there are no more compilation units left to traverse, they return DW_DLV_NO_ENTRY.

ERRORS

These functions can fail with the following error: