1.\" $NetBSD: dwarf_next_cu_header.3,v 1.4 2020/11/26 22:51:35 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 3644 2018-10-15 19:55:01Z 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.Ar dbg 99should reference a DWARF debug context allocated using 100.Xr dwarf_init 3 . 101If argument 102.Ar is_info 103is set to 1, 104the function returns information for compilation units found in the 105.Dq \&.debug_info 106section. 107If argument 108.Ar is_info 109is set to 0, 110the function returns information for type units found in the 111.Dq \&.debug_types 112sections. 113Argument 114.Ar cu_length 115should point to a location that will be set to the 116length of the compilation or type unit. 117Argument 118.Ar cu_version 119should point to a location that will be set to the 120version number for the compilation or type unit. 121Argument 122.Ar 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.Ar 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.Ar 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.Ar 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.Ar type_signature 145and 146.Ar type_offset 147is only needed for processing type units. 148Argument 149.Ar 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.Ar 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.Ar 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.Ar 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.Ar is_info , 176.Ar type_signature 177and 178.Ar 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.Ar cu_offset_size 186and 187.Ar cu_extension_size . 188.Pp 189A value of NULL may be used for any of the arguments 190.Ar cu_length , 191.Ar cu_version , 192.Ar cu_abbrev_offset , 193.Ar cu_pointer_size , 194.Ar cu_offset_size , 195.Ar cu_extension_size , 196.Ar type_signature , 197.Ar type_offset , 198.Ar cu_next_offset 199and 200.Ar err 201if the caller is not interested in the respective value. 202.Ss Iterating Through Compilation Units in a Debug Context 203The first call to function 204.Fn dwarf_next_cu_header_c 205for a given debug context with argument 206.Ar is_info 207set to 1 will return information about the first 208compilation unit in the 209.Dq \&.debug_info 210section. 211Subsequent calls to the function will iterate through the remaining 212compilation units in the section. 213On stepping past the last compilation unit in the section, 214function 215.Fn dwarf_next_cu_header_c 216returns 217.Dv DW_DLV_NO_ENTRY 218and resets its internal state. 219The next call to the function will restart from the first compilation 220unit in the section. 221.Ss Iterating Through Type Units in a Debug Context 222When a DWARF debug context is allocated using 223.Xr dwarf_init 3 , 224an internal pointer associated with the context will point to the first 225.Dq \&.debug_types 226section found in the debug object. 227The first call to function 228.Fn dwarf_next_cu_header_c 229for the debug context with argument 230.Ar is_info 231set to 0 will return information about the first 232type unit in that 233.Dq \&.debug_types 234section. 235Subsequent calls to the function will iterate through the remaining 236type units in the section. 237On stepping past the last type unit in the debug context, 238function 239.Fn dwarf_next_cu_header_c 240returns 241.Dv DW_DLV_NO_ENTRY 242and resets its internal state. 243The next call to the function will restart from the first type 244unit in the 245.Dq \&.debug_types 246section. 247.Pp 248If the debug object contains multiple 249.Dq \&.debug_types 250sections, the function 251.Fn dwarf_next_types_section 252can be called to move the internal pointer to the next 253.Dq \&.debug_types 254section. 255As a result, subsequent calls of the function 256.Fn dwarf_next_cu_header_c 257will operate on the new 258.Dq \&.debug_types 259section. 260Function 261.Fn dwarf_next_types_section 262returns 263.Dv DW_DLV_NO_ENTRY 264when there are no more 265.Dq \&.debug_types 266sections left in the debug object. 267.Sh RETURN VALUES 268On success, these functions return 269.Dv DW_DLV_OK . 270In case of an error, they return 271.Dv DW_DLV_ERROR 272and set argument 273.Ar err . 274When there are no more compilation units left to traverse, they return 275.Dv DW_DLV_NO_ENTRY . 276.Sh ERRORS 277These functions can fail with the following error: 278.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" 279.It Bq Er DW_DLE_ARGUMENT 280Argument 281.Va dbg 282was NULL. 283.El 284.Sh SEE ALSO 285.Xr dwarf 3 , 286.Xr dwarf_get_cu_die_offset_given_cu_header_offset 3 , 287.Xr dwarf_init 3 , 288.Xr dwarf_next_types_section 3 , 289.Xr dwarf_siblingof 3 290