--- name: "dwarf_next_cu_header" section: "3" platform: "freebsd" package: "base" version: "16.0-CURRENT-20261027-61c70dc16a79" release: "FreeBSD 16.0-CURRENT (2026-10-27)" platforms: ["freebsd"] url: "https://new.carta.tech/dwarf_next_cu_header" --- # dwarf\_next\_cu\_header(3) step through compilation units in a DWARF debug context ## NAME **dwarf\_next\_cu\_header**, **dwarf\_next\_cu\_header\_b**, **dwarf\_next\_cu\_header\_c** – step through compilation units in a DWARF debug context ## LIBRARY library “libdwarf” ## SYNOPSIS **#include \** *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*); *int*\ **dwarf\_next\_cu\_header\_c**(*Dwarf\_Debug dbg*, *Dwarf\_Bool is\_info*, *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\_Sig8 \*type\_signature*, *Dwarf\_Unsigned \*type\_offset*, *Dwarf\_Unsigned \*cu\_next\_offset*, *Dwarf\_Error \*err*); ## DESCRIPTION These functions are used to step through compilation or type units associated with a DWARF debug context, optionally returning information about the unit. Function **dwarf\_next\_cu\_header\_c**() is the API recommended for new application code. Function **dwarf\_next\_cu\_header**() and **dwarf\_next\_cu\_header\_b**() can only operate on compilation units associated with the “.debug\_info” section. They are less general than function **dwarf\_next\_cu\_header\_c**(), and are deprecated for use by new application code. Argument *dbg* should reference a DWARF debug context allocated using [dwarf\_init(3)](/dwarf_init/3.md). If argument *is\_info* is set to 1, the function returns information for compilation units found in the “.debug\_info” section. If argument *is\_info* is set to 0, the function returns information for type units found in the “.debug\_types” sections. Argument *cu\_length* should point to a location that will be set to the length of the compilation or type unit. Argument *cu\_version* should point to a location that will be set to the version number for the compilation or type 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 or type 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 or type 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 *type\_signature* and *type\_offset* is only needed for processing type units. Argument *type\_signature* should point to a location that will be set to the 64-bit unique signature of the type described in the type unit. Argument *type\_offset* should point to a location that will be set to the offset of the debugging information entry that describes the type. 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, or the offset of the next type unit header in the “.debug\_types” section. Argument *err* should point to a location that will hold an error descriptor in case of an error. Function **dwarf\_next\_cu\_header\_b**() is identical to function **dwarf\_next\_cu\_header\_c**() except that it does not provide arguments *is\_info*, *type\_signature* and *type\_offset*. Function **dwarf\_next\_cu\_header**() is identical to function **dwarf\_next\_cu\_header\_b**() except that it does not provide arguments *cu\_offset\_size* and *cu\_extension\_size*. 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*, *type\_signature*, *type\_offset*, *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 function **dwarf\_next\_cu\_header\_c**() for a given debug context with argument *is\_info* set to 1 will return information about the first compilation unit in the “.debug\_info” section. Subsequent calls to the function will iterate through the remaining compilation units in the section. On stepping past the last compilation unit in the section, function **dwarf\_next\_cu\_header\_c**() returns DW\_DLV\_NO\_ENTRY and resets its internal state. The next call to the function will restart from the first compilation unit in the section. ### Iterating Through Type Units in a Debug Context When a DWARF debug context is allocated using [dwarf\_init(3)](/dwarf_init/3.md), an internal pointer associated with the context will point to the first “.debug\_types” section found in the debug object. The first call to function **dwarf\_next\_cu\_header\_c**() for the debug context with argument *is\_info* set to 0 will return information about the first type unit in that “.debug\_types” section. Subsequent calls to the function will iterate through the remaining type units in the section. On stepping past the last type unit in the debug context, function **dwarf\_next\_cu\_header\_c**() returns DW\_DLV\_NO\_ENTRY and resets its internal state. The next call to the function will restart from the first type unit in the “.debug\_types” section. If the debug object contains multiple “.debug\_types” sections, the function **dwarf\_next\_types\_section**() can be called to move the internal pointer to the next “.debug\_types” section. As a result, subsequent calls of the function **dwarf\_next\_cu\_header\_c**() will operate on the new “.debug\_types” section. Function **dwarf\_next\_types\_section**() returns DW\_DLV\_NO\_ENTRY when there are no more “.debug\_types” sections left in the debug object. ## 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: - \[DW\_DLE\_ARGUMENT\] Argument *dbg* was NULL. ## SEE ALSO [dwarf(3)](/dwarf/3.md), [dwarf\_get\_cu\_die\_offset\_given\_cu\_header\_offset(3)](/dwarf_get_cu_die_offset_given_cu_header_offset/3.md), [dwarf\_init(3)](/dwarf_init/3.md), [dwarf\_next\_types\_section(3)](/dwarf_next_types_section/3.md), [dwarf\_siblingof(3)](/dwarf_siblingof/3.md)