1.\" Copyright (c) 2010,2014 Kai Wang 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $Id: dwarf_next_cu_header.3 3128 2014-12-21 20:06:22Z jkoshy $ 26.\" 27.Dd December 21, 2014 28.Os 29.Dt DWARF_NEXT_CU_HEADER 3 30.Sh NAME 31.Nm dwarf_next_cu_header , 32.Nm dwarf_next_cu_header_b , 33.Nm dwarf_next_cu_header_c 34.Nd step through compilation units in a DWARF debug context 35.Sh LIBRARY 36.Lb libdwarf 37.Sh SYNOPSIS 38.In libdwarf.h 39.Ft int 40.Fo dwarf_next_cu_header 41.Fa "Dwarf_Debug dbg" 42.Fa "Dwarf_Unsigned *cu_length" 43.Fa "Dwarf_Half *cu_version" 44.Fa "Dwarf_Off *cu_abbrev_offset" 45.Fa "Dwarf_Half *cu_pointer_size" 46.Fa "Dwarf_Unsigned *cu_next_offset" 47.Fa "Dwarf_Error *err" 48.Fc 49.Ft int 50.Fo dwarf_next_cu_header_b 51.Fa "Dwarf_Debug dbg" 52.Fa "Dwarf_Unsigned *cu_length" 53.Fa "Dwarf_Half *cu_version" 54.Fa "Dwarf_Off *cu_abbrev_offset" 55.Fa "Dwarf_Half *cu_pointer_size" 56.Fa "Dwarf_Half *cu_offset_size" 57.Fa "Dwarf_Half *cu_extension_size" 58.Fa "Dwarf_Unsigned *cu_next_offset" 59.Fa "Dwarf_Error *err" 60.Fc 61.Ft int 62.Fo dwarf_next_cu_header_c 63.Fa "Dwarf_Debug dbg" 64.Fa "Dwarf_Bool is_info" 65.Fa "Dwarf_Unsigned *cu_length" 66.Fa "Dwarf_Half *cu_version" 67.Fa "Dwarf_Off *cu_abbrev_offset" 68.Fa "Dwarf_Half *cu_pointer_size" 69.Fa "Dwarf_Half *cu_offset_size" 70.Fa "Dwarf_Half *cu_extension_size" 71.Fa "Dwarf_Sig8 *type_signature" 72.Fa "Dwarf_Unsigned *type_offset" 73.Fa "Dwarf_Unsigned *cu_next_offset" 74.Fa "Dwarf_Error *err" 75.Fc 76.Sh DESCRIPTION 77These functions are used to step through compilation or type units 78associated with a DWARF debug context, optionally returning information 79about the unit. 80.Pp 81Function 82.Fn dwarf_next_cu_header_c 83is the API recommended for new application code. 84Function 85.Fn dwarf_next_cu_header 86and 87.Fn dwarf_next_cu_header_b 88can only operate on compilation units associated with the 89.Dq \&.debug_info 90section. 91They are less general than function 92.Fn dwarf_next_cu_header_c , 93and are deprecated for use by new application code. 94.Pp 95Argument 96.Ar dbg 97should reference a DWARF debug context allocated using 98.Xr dwarf_init 3 . 99If argument 100.Ar is_info 101is set to 1, 102the function returns information for compilation units found in the 103.Dq \&.debug_info 104section. 105If argument 106.Ar is_info 107is set to 0, 108the function returns information for type units found in the 109.Dq \&.debug_types 110sections. 111Argument 112.Ar cu_length 113should point to a location that will be set to the 114length of the compilation or type unit. 115Argument 116.Ar cu_version 117should point to a location that will be set to the 118version number for the compilation or type unit. 119Argument 120.Ar cu_abbrev_offset 121should point to a location that will be set to the 122starting offset (in the 123.Dq .debug_abbrev 124section) of the set of debugging information entry abbreviations 125associated with this compilation or type unit. 126Argument 127.Ar cu_pointer_size 128should point to a location that will be set to the 129size in bytes of an address for the machine architecture of the 130underlying object being debugged. 131Argument 132.Ar cu_offset_size 133should point to a location that will be set to the 134size in bytes for a DWARF offset in the compilation or type unit. 135Argument 136.Ar cu_extension_size 137is only needed for processing MIPS/IRIX objects that use 138a non-standard DWARF format. 139It should point to a location that will be set to 4 for normal 140objects and to 0 for non-standard ones. 141Argument 142.Ar type_signature 143and 144.Ar type_offset 145is only needed for processing type units. 146Argument 147.Ar type_signature 148should point to a location that will be set to the 64-bit unique signature 149of the type described in the type unit. 150Argument 151.Ar type_offset 152should point to a location that will be set to the offset of the debugging 153information entry that describes the type. 154Argument 155.Ar cu_next_offset 156should point to a location that will be set to the 157offset of the next compilation unit header in the 158.Dq \&.debug_info 159section, 160or the offset of the next type unit header in the 161.Dq \&.debug_types 162section. 163Argument 164.Ar err 165should point to a location that will hold an error descriptor in case 166of an error. 167.Pp 168Function 169.Fn dwarf_next_cu_header_b 170is identical to function 171.Fn dwarf_next_cu_header_c 172except that it does not provide arguments 173.Ar is_info , 174.Ar type_signature 175and 176.Ar type_offset . 177.Pp 178Function 179.Fn dwarf_next_cu_header 180is identical to function 181.Fn dwarf_next_cu_header_b 182except that it does not provide arguments 183.Ar cu_offset_size 184and 185.Ar cu_extension_size . 186.Pp 187A value of NULL may be used for any of the arguments 188.Ar cu_length , 189.Ar cu_version , 190.Ar cu_abbrev_offset , 191.Ar cu_pointer_size , 192.Ar cu_offset_size , 193.Ar cu_extension_size , 194.Ar type_signature , 195.Ar type_offset , 196.Ar cu_next_offset 197and 198.Ar err 199if the caller is not interested in the respective value. 200.Ss Iterating Through Compilation Units in a Debug Context 201.Pp 202The first call to function 203.Fn dwarf_next_cu_header_c 204for a given debug context with argument 205.Ar is_info 206set to 1 will return information about the first 207compilation unit in the 208.Dq \&.debug_info 209section. 210Subsequent calls to the function will iterate through the remaining 211compilation units in the section. 212On stepping past the last compilation unit in the section, 213function 214.Fn dwarf_next_cu_header_c 215returns 216.Dv DW_DLV_NO_ENTRY 217and resets its internal state. 218The next call to the function will restart from the first compilation 219unit in the section. 220.Ss Iterating Through Type Units in a Debug Context 221When a DWARF debug context is allocated using 222.Xr dwarf_init 3 , 223an internal pointer assoicated with the context will point to the 224fisrt 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