1.\" $NetBSD: dwarf_next_cu_header.3,v 1.3 2016/02/20 02:43:41 christos 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 3182 2015-04-10 16:08:10Z emaste 28.\" 29.Dd December 21, 2014 30.Os 31.Dt DWARF_NEXT_CU_HEADER 3 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 203.Pp 204The first call to function 205.Fn dwarf_next_cu_header_c 206for a given debug context with argument 207.Ar is_info 208set to 1 will return information about the first 209compilation unit in the 210.Dq \&.debug_info 211section. 212Subsequent calls to the function will iterate through the remaining 213compilation units in the section. 214On stepping past the last compilation unit in the section, 215function 216.Fn dwarf_next_cu_header_c 217returns 218.Dv DW_DLV_NO_ENTRY 219and resets its internal state. 220The next call to the function will restart from the first compilation 221unit in the section. 222.Ss Iterating Through Type Units in a Debug Context 223When a DWARF debug context is allocated using 224.Xr dwarf_init 3 , 225an internal pointer associated with the context will point to the first 226.Dq \&.debug_types 227section found in the debug object. 228The first call to function 229.Fn dwarf_next_cu_header_c 230for the debug context with argument 231.Ar is_info 232set to 0 will return information about the first 233type unit in that 234.Dq \&.debug_types 235section. 236Subsequent calls to the function will iterate through the remaining 237type units in the section. 238On stepping past the last type unit in the debug context, 239function 240.Fn dwarf_next_cu_header_c 241returns 242.Dv DW_DLV_NO_ENTRY 243and resets its internal state. 244The next call to the function will restart from the first type 245unit in the 246.Dq \&.debug_types 247section. 248.Pp 249If the debug object contains multiple 250.Dq \&.debug_types 251sections, the function 252.Fn dwarf_next_types_section 253can be called to move the internal pointer to the next 254.Dq \&.debug_types 255section. 256As a result, subsequent calls of the function 257.Fn dwarf_next_cu_header_c 258will operate on the new 259.Dq \&.debug_types 260section. 261Function 262.Fn dwarf_next_types_section 263returns 264.Dv DW_DLV_NO_ENTRY 265when there are no more 266.Dq \&.debug_types 267sections left in the debug object. 268.Sh RETURN VALUES 269On success, these functions return 270.Dv DW_DLV_OK . 271In case of an error, they return 272.Dv DW_DLV_ERROR 273and set argument 274.Ar err . 275When there are no more compilation units left to traverse, they return 276.Dv DW_DLV_NO_ENTRY . 277.Sh ERRORS 278These functions can fail with the following error: 279.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" 280.It Bq Er DW_DLE_ARGUMENT 281Argument 282.Va dbg 283was NULL. 284.El 285.Sh SEE ALSO 286.Xr dwarf 3 , 287.Xr dwarf_get_cu_die_offset_given_cu_header_offset 3 , 288.Xr dwarf_init 3 , 289.Xr dwarf_next_types_section 3 , 290.Xr dwarf_siblingof 3 291