contrib/elftoolchain/libdwarf/dwarf_next_cu_header.3

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