1.\" $NetBSD: dwarf_next_cu_header.3,v 1.5 2022/03/14 20:50:48 jkoshy Exp $ 2.\" 3.\" Copyright (c) 2010,2014 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 3963 2022-03-12 16:07:32Z jkoshy 28.\" 29.Dd December 21, 2014 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.Nd step through compilation units in a DWARF debug context 37.Sh LIBRARY 38.Lb libdwarf 39.Sh SYNOPSIS 40.In libdwarf.h 41.Ft int 42.Fo dwarf_next_cu_header 43.Fa "Dwarf_Debug dbg" 44.Fa "Dwarf_Unsigned *cu_length" 45.Fa "Dwarf_Half *cu_version" 46.Fa "Dwarf_Off *cu_abbrev_offset" 47.Fa "Dwarf_Half *cu_pointer_size" 48.Fa "Dwarf_Unsigned *cu_next_offset" 49.Fa "Dwarf_Error *err" 50.Fc 51.Ft int 52.Fo dwarf_next_cu_header_b 53.Fa "Dwarf_Debug dbg" 54.Fa "Dwarf_Unsigned *cu_length" 55.Fa "Dwarf_Half *cu_version" 56.Fa "Dwarf_Off *cu_abbrev_offset" 57.Fa "Dwarf_Half *cu_pointer_size" 58.Fa "Dwarf_Half *cu_offset_size" 59.Fa "Dwarf_Half *cu_extension_size" 60.Fa "Dwarf_Unsigned *cu_next_offset" 61.Fa "Dwarf_Error *err" 62.Fc 63.Ft int 64.Fo dwarf_next_cu_header_c 65.Fa "Dwarf_Debug dbg" 66.Fa "Dwarf_Bool is_info" 67.Fa "Dwarf_Unsigned *cu_length" 68.Fa "Dwarf_Half *cu_version" 69.Fa "Dwarf_Off *cu_abbrev_offset" 70.Fa "Dwarf_Half *cu_pointer_size" 71.Fa "Dwarf_Half *cu_offset_size" 72.Fa "Dwarf_Half *cu_extension_size" 73.Fa "Dwarf_Sig8 *type_signature" 74.Fa "Dwarf_Unsigned *type_offset" 75.Fa "Dwarf_Unsigned *cu_next_offset" 76.Fa "Dwarf_Error *err" 77.Fc 78.Sh DESCRIPTION 79These functions are used to step through compilation or type units 80associated with a DWARF debug context, optionally returning information 81about the unit. 82.Pp 83Function 84.Fn dwarf_next_cu_header_c 85is the API recommended for new application code. 86Function 87.Fn dwarf_next_cu_header 88and 89.Fn dwarf_next_cu_header_b 90can only operate on compilation units associated with the 91.Dq \&.debug_info 92section. 93They are less general than function 94.Fn dwarf_next_cu_header_c , 95and are deprecated for use by new application code. 96.Pp 97Argument 98.Fa dbg 99should reference a DWARF debug context allocated using 100.Xr dwarf_init 3 . 101If argument 102.Fa is_info 103is set to 1, 104the function returns information for compilation units found in the 105.Dq \&.debug_info 106section. 107If argument 108.Fa is_info 109is set to 0, 110the function returns information for type units found in the 111.Dq \&.debug_types 112sections. 113Argument 114.Fa cu_length 115should point to a location that will be set to the 116length of the compilation or type unit. 117Argument 118.Fa cu_version 119should point to a location that will be set to the 120version number for the compilation or type unit. 121Argument 122.Fa cu_abbrev_offset 123should point to a location that will be set to the 124starting offset (in the 125.Dq .debug_abbrev 126section) of the set of debugging information entry abbreviations 127associated with this compilation or type unit. 128Argument 129.Fa cu_pointer_size 130should point to a location that will be set to the 131size in bytes of an address for the machine architecture of the 132underlying object being debugged. 133Argument 134.Fa cu_offset_size 135should point to a location that will be set to the 136size in bytes for a DWARF offset in the compilation or type unit. 137Argument 138.Fa cu_extension_size 139is only needed for processing MIPS/IRIX objects that use 140a non-standard DWARF format. 141It should point to a location that will be set to 4 for normal 142objects and to 0 for non-standard ones. 143Argument 144.Fa type_signature 145and 146.Fa type_offset 147is only needed for processing type units. 148Argument 149.Fa type_signature 150should point to a location that will be set to the 64-bit unique signature 151of the type described in the type unit. 152Argument 153.Fa type_offset 154should point to a location that will be set to the offset of the debugging 155information entry that describes the type. 156Argument 157.Fa cu_next_offset 158should point to a location that will be set to the 159offset of the next compilation unit header in the 160.Dq \&.debug_info 161section, 162or the offset of the next type unit header in the 163.Dq \&.debug_types 164section. 165Argument 166.Fa err 167should point to a location that will hold an error descriptor in case 168of an error. 169.Pp 170Function 171.Fn dwarf_next_cu_header_b 172is identical to function 173.Fn dwarf_next_cu_header_c 174except that it does not provide arguments 175.Fa is_info , 176.Fa type_signature 177and 178.Fa type_offset . 179.Pp 180Function 181.Fn dwarf_next_cu_header 182is identical to function 183.Fn dwarf_next_cu_header_b 184except that it does not provide arguments 185.Fa cu_offset_size 186and 187.Fa cu_extension_size . 188.Pp 189A value of 190.Dv NULL 191may be used for any of the arguments 192.Fa cu_length , 193.Fa cu_version , 194.Fa cu_abbrev_offset , 195.Fa cu_pointer_size , 196.Fa cu_offset_size , 197.Fa cu_extension_size , 198.Fa type_signature , 199.Fa type_offset , 200.Fa cu_next_offset 201and 202.Fa err 203if the caller is not interested in the respective value. 204.Ss Iterating Through Compilation Units in a Debug Context 205The first call to function 206.Fn dwarf_next_cu_header_c 207for a given debug context with argument 208.Fa is_info 209set to 1 will return information about the first 210compilation unit in the 211.Dq \&.debug_info 212section. 213Subsequent calls to the function will iterate through the remaining 214compilation units in the section. 215On stepping past the last compilation unit in the section, 216function 217.Fn dwarf_next_cu_header_c 218returns 219.Dv DW_DLV_NO_ENTRY 220and resets its internal state. 221The next call to the function will restart from the first compilation 222unit in the section. 223.Ss Iterating Through Type Units in a Debug Context 224When a DWARF debug context is allocated using 225.Xr dwarf_init 3 , 226an internal pointer associated with the context will point to the first 227.Dq \&.debug_types 228section found in the debug object. 229The first call to function 230.Fn dwarf_next_cu_header_c 231for the debug context with argument 232.Fa is_info 233set to 0 will return information about the first 234type unit in that 235.Dq \&.debug_types 236section. 237Subsequent calls to the function will iterate through the remaining 238type units in the section. 239On stepping past the last type unit in the debug context, 240function 241.Fn dwarf_next_cu_header_c 242returns 243.Dv DW_DLV_NO_ENTRY 244and resets its internal state. 245The next call to the function will restart from the first type 246unit in the 247.Dq \&.debug_types 248section. 249.Pp 250If the debug object contains multiple 251.Dq \&.debug_types 252sections, the function 253.Fn dwarf_next_types_section 254can be called to move the internal pointer to the next 255.Dq \&.debug_types 256section. 257As a result, subsequent calls of the function 258.Fn dwarf_next_cu_header_c 259will operate on the new 260.Dq \&.debug_types 261section. 262Function 263.Fn dwarf_next_types_section 264returns 265.Dv DW_DLV_NO_ENTRY 266when there are no more 267.Dq \&.debug_types 268sections left in the debug object. 269.Sh RETURN VALUES 270On success, these functions return 271.Dv DW_DLV_OK . 272In case of an error, they return 273.Dv DW_DLV_ERROR 274and set argument 275.Fa err . 276When there are no more compilation units left to traverse, they return 277.Dv DW_DLV_NO_ENTRY . 278.Sh ERRORS 279These functions can fail with the following error: 280.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" 281.It Bq Er DW_DLE_ARGUMENT 282Argument 283.Va dbg 284was 285.Dv NULL . 286.El 287.Sh SEE ALSO 288.Xr dwarf 3 , 289.Xr dwarf_get_cu_die_offset_given_cu_header_offset 3 , 290.Xr dwarf_init 3 , 291.Xr dwarf_next_types_section 3 , 292.Xr dwarf_siblingof 3 293