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