1.\" $NetBSD: dwarf_next_cu_header.3,v 1.6 2024/03/03 17:37:31 christos Exp $ 2.\" 3.\" Copyright (c) 2010,2014,2023 Kai Wang 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.\" Id: dwarf_next_cu_header.3 4013 2023-10-14 22:40:50Z kaiwang27 28.\" 29.Dd October 15, 2023 30.Dt DWARF_NEXT_CU_HEADER 3 31.Os 32.Sh NAME 33.Nm dwarf_next_cu_header , 34.Nm dwarf_next_cu_header_b , 35.Nm dwarf_next_cu_header_c , 36.Nm dwarf_next_cu_header_d 37.Nd step through compilation units in a DWARF debug context 38.Sh LIBRARY 39.Lb libdwarf 40.Sh SYNOPSIS 41.In libdwarf.h 42.Ft int 43.Fo dwarf_next_cu_header 44.Fa "Dwarf_Debug dbg" 45.Fa "Dwarf_Unsigned *cu_length" 46.Fa "Dwarf_Half *cu_version" 47.Fa "Dwarf_Off *cu_abbrev_offset" 48.Fa "Dwarf_Half *cu_pointer_size" 49.Fa "Dwarf_Unsigned *cu_next_offset" 50.Fa "Dwarf_Error *err" 51.Fc 52.Ft int 53.Fo dwarf_next_cu_header_b 54.Fa "Dwarf_Debug dbg" 55.Fa "Dwarf_Unsigned *cu_length" 56.Fa "Dwarf_Half *cu_version" 57.Fa "Dwarf_Off *cu_abbrev_offset" 58.Fa "Dwarf_Half *cu_pointer_size" 59.Fa "Dwarf_Half *cu_offset_size" 60.Fa "Dwarf_Half *cu_extension_size" 61.Fa "Dwarf_Unsigned *cu_next_offset" 62.Fa "Dwarf_Error *err" 63.Fc 64.Ft int 65.Fo dwarf_next_cu_header_c 66.Fa "Dwarf_Debug dbg" 67.Fa "Dwarf_Bool is_info" 68.Fa "Dwarf_Unsigned *cu_length" 69.Fa "Dwarf_Half *cu_version" 70.Fa "Dwarf_Off *cu_abbrev_offset" 71.Fa "Dwarf_Half *cu_pointer_size" 72.Fa "Dwarf_Half *cu_offset_size" 73.Fa "Dwarf_Half *cu_extension_size" 74.Fa "Dwarf_Sig8 *type_signature" 75.Fa "Dwarf_Unsigned *type_offset" 76.Fa "Dwarf_Unsigned *cu_next_offset" 77.Fa "Dwarf_Error *err" 78.Fc 79.Ft int 80.Fo dwarf_next_cu_header_d 81.Fa "Dwarf_Debug dbg" 82.Fa "Dwarf_Bool is_info" 83.Fa "Dwarf_Unsigned *cu_length" 84.Fa "Dwarf_Half *cu_version" 85.Fa "Dwarf_Off *cu_abbrev_offset" 86.Fa "Dwarf_Half *cu_pointer_size" 87.Fa "Dwarf_Half *cu_offset_size" 88.Fa "Dwarf_Half *cu_extension_size" 89.Fa "Dwarf_Sig8 *type_signature" 90.Fa "Dwarf_Unsigned *type_offset" 91.Fa "Dwarf_Unsigned *cu_next_offset" 92.Fa "Dwarf_Half *cu_type" 93.Fa "Dwarf_Error *err" 94.Fc 95.Sh DESCRIPTION 96These functions are used to step through compilation or type units 97associated with a DWARF debug context, optionally returning information 98about the unit. 99.Pp 100Function 101.Fn dwarf_next_cu_header_d 102is the API recommended for new application code. 103Function 104.Fn dwarf_next_cu_header_c 105can not return the unit type defined by the DWARF5 standard. 106Function 107.Fn dwarf_next_cu_header 108and 109.Fn dwarf_next_cu_header_b 110can only operate on compilation units associated with the 111.Dq \&.debug_info 112section. 113The earlier revisions are less general than function 114.Fn dwarf_next_cu_header_d , 115and are deprecated for use by new application code. 116.Pp 117Argument 118.Fa dbg 119should reference a DWARF debug context allocated using 120.Xr dwarf_init 3 . 121If argument 122.Fa is_info 123is set to 1, 124the function returns information for compilation units found in the 125.Dq \&.debug_info 126section. 127If argument 128.Fa is_info 129is set to 0, 130the function returns information for type units found in the 131.Dq \&.debug_types 132sections. 133Argument 134.Fa cu_length 135should point to a location that will be set to the 136length of the compilation or type unit. 137Argument 138.Fa cu_version 139should point to a location that will be set to the 140version number for the compilation or type unit. 141Argument 142.Fa cu_abbrev_offset 143should point to a location that will be set to the 144starting offset (in the 145.Dq .debug_abbrev 146section) of the set of debugging information entry abbreviations 147associated with this compilation or type unit. 148Argument 149.Fa cu_pointer_size 150should point to a location that will be set to the 151size in bytes of an address for the machine architecture of the 152underlying object being debugged. 153Argument 154.Fa cu_offset_size 155should point to a location that will be set to the 156size in bytes for a DWARF offset in the compilation or type unit. 157Argument 158.Fa cu_extension_size 159is only needed for processing MIPS/IRIX objects that use 160a non-standard DWARF format. 161It should point to a location that will be set to 4 for normal 162objects and to 0 for non-standard ones. 163Argument 164.Fa type_signature 165and 166.Fa type_offset 167is only needed for processing type units. 168Argument 169.Fa type_signature 170should point to a location that will be set to the 64-bit unique signature 171of the type described in the type unit. 172Argument 173.Fa type_offset 174should point to a location that will be set to the offset of the debugging 175information entry that describes the type. 176Argument 177.Fa cu_next_offset 178should point to a location that will be set to the 179offset of the next compilation unit header in the 180.Dq \&.debug_info 181section, 182or the offset of the next type unit header in the 183.Dq \&.debug_types 184section. 185Argument 186.Fa cu_type 187should point to a location that will be set to the 188type of the compilation unit. 189Argument 190.Fa err 191should point to a location that will hold an error descriptor in case 192of an error. 193.Pp 194Function 195.Fn dwarf_next_cu_header_c 196is identical to function 197.Fn dwarf_next_cu_header_d 198except that it does not provide argument 199.Fa cu_type . 200.Pp 201Function 202.Fn dwarf_next_cu_header_b 203is identical to function 204.Fn dwarf_next_cu_header_c 205except that it does not provide arguments 206.Fa is_info , 207.Fa type_signature 208and 209.Fa type_offset . 210.Pp 211Function 212.Fn dwarf_next_cu_header 213is identical to function 214.Fn dwarf_next_cu_header_b 215except that it does not provide arguments 216.Fa cu_offset_size 217and 218.Fa cu_extension_size . 219.Pp 220A value of 221.Dv NULL 222may be used for any of the arguments 223.Fa cu_length , 224.Fa cu_version , 225.Fa cu_abbrev_offset , 226.Fa cu_pointer_size , 227.Fa cu_offset_size , 228.Fa cu_extension_size , 229.Fa type_signature , 230.Fa type_offset , 231.Fa cu_next_offset , 232.Fa cu_type 233and 234.Fa err 235if the caller is not interested in the respective value. 236.Ss Iterating Through Compilation Units in a Debug Context 237The first call to function 238.Fn dwarf_next_cu_header_c 239for a given debug context with argument 240.Fa is_info 241set to 1 will return information about the first 242compilation unit in the 243.Dq \&.debug_info 244section. 245Subsequent calls to the function will iterate through the remaining 246compilation units in the section. 247On stepping past the last compilation unit in the section, 248function 249.Fn dwarf_next_cu_header_d 250returns 251.Dv DW_DLV_NO_ENTRY 252and resets its internal state. 253The next call to the function will restart from the first compilation 254unit in the section. 255.Ss Iterating Through Type Units in a Debug Context 256When a DWARF debug context is allocated using 257.Xr dwarf_init 3 , 258an internal pointer associated with the context will point to the first 259.Dq \&.debug_types 260section found in the debug object. 261The first call to function 262.Fn dwarf_next_cu_header_d 263for the debug context with argument 264.Fa is_info 265set to 0 will return information about the first 266type unit in that 267.Dq \&.debug_types 268section. 269Subsequent calls to the function will iterate through the remaining 270type units in the section. 271On stepping past the last type unit in the debug context, 272function 273.Fn dwarf_next_cu_header_d 274returns 275.Dv DW_DLV_NO_ENTRY 276and resets its internal state. 277The next call to the function will restart from the first type 278unit in the 279.Dq \&.debug_types 280section. 281.Pp 282If the debug object contains multiple 283.Dq \&.debug_types 284sections, the function 285.Fn dwarf_next_types_section 286can be called to move the internal pointer to the next 287.Dq \&.debug_types 288section. 289As a result, subsequent calls of the function 290.Fn dwarf_next_cu_header_d 291will operate on the new 292.Dq \&.debug_types 293section. 294Function 295.Fn dwarf_next_types_section 296returns 297.Dv DW_DLV_NO_ENTRY 298when there are no more 299.Dq \&.debug_types 300sections left in the debug object. 301.Sh RETURN VALUES 302On success, these functions return 303.Dv DW_DLV_OK . 304In case of an error, they return 305.Dv DW_DLV_ERROR 306and set argument 307.Fa err . 308When there are no more compilation units left to traverse, they return 309.Dv DW_DLV_NO_ENTRY . 310.Sh ERRORS 311These functions can fail with the following error: 312.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" 313.It Bq Er DW_DLE_ARGUMENT 314Argument 315.Va dbg 316was 317.Dv NULL . 318.El 319.Sh SEE ALSO 320.Xr dwarf 3 , 321.Xr dwarf_get_cu_die_offset_given_cu_header_offset 3 , 322.Xr dwarf_init 3 , 323.Xr dwarf_next_types_section 3 , 324.Xr dwarf_siblingof 3 325