contrib/elftoolchain/libdwarf/dwarf_next_cu_header.3

   1 .\" Copyright (c) 2010 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 2074 2011-10-27 03:34:33Z jkoshy $
  26 .\"
  27 .Dd July 24, 2010
  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 .Nd step through compilation units in a DWARF debug context
  34 .Sh LIBRARY
  35 .Lb libdwarf
  36 .Sh SYNOPSIS
  37 .In libdwarf.h
  38 .Ft int
  39 .Fo dwarf_next_cu_header
  40 .Fa "Dwarf_Debug dbg"
  41 .Fa "Dwarf_Unsigned *cu_length"
  42 .Fa "Dwarf_Half *cu_version"
  43 .Fa "Dwarf_Off *cu_abbrev_offset"
  44 .Fa "Dwarf_Half *cu_pointer_size"
  45 .Fa "Dwarf_Unsigned *cu_next_offset"
  46 .Fa "Dwarf_Error *err"
  47 .Fc
  48 .Ft int
  49 .Fo dwarf_next_cu_header_b
  50 .Fa "Dwarf_Debug dbg"
  51 .Fa "Dwarf_Unsigned *cu_length"
  52 .Fa "Dwarf_Half *cu_version"
  53 .Fa "Dwarf_Off *cu_abbrev_offset"
  54 .Fa "Dwarf_Half *cu_pointer_size"
  55 .Fa "Dwarf_Half *cu_offset_size"
  56 .Fa "Dwarf_Half *cu_extension_size"
  57 .Fa "Dwarf_Unsigned *cu_next_offset"
  58 .Fa "Dwarf_Error *err"
  59 .Fc
  60 .Sh DESCRIPTION
  61 These functions are used to step through compilation unit contexts
  62 associated with a DWARF debug context, optionally returning information
  63 about the unit.
  64 .Pp
  65 Function
  66 .Fn dwarf_next_cu_header_b
  67 is the API recommended for new application code.
  68 Argument
  69 .Ar dbg
  70 should reference a DWARF debug context allocated using
  71 .Xr dwarf_init 3 .
  72 Argument
  73 .Ar cu_length
  74 should point to a location that will be set to the
  75 length of the compilation unit.
  76 Argument
  77 .Ar cu_version
  78 should point to a location that will be set to the
  79 version number for the compilation unit.
  80 Argument
  81 .Ar cu_abbrev_offset
  82 should point to a location that will be set to the
  83 starting offset (in the
  84 .Dq .debug_abbrev
  85 section) of the set of debugging information entry abbreviations
  86 associated with this compilation unit.
  87 Argument
  88 .Ar cu_pointer_size
  89 should point to a location that will be set to the
  90 size in bytes of an address for the machine architecture of the
  91 underlying object being debugged.
  92 Argument
  93 .Ar cu_offset_size
  94 should point to a location that will be set to the
  95 size in bytes for a DWARF offset in the compilation unit.
  96 Argument
  97 .Ar cu_extension_size
  98 is only needed for processing MIPS/IRIX objects that use
  99 a non-standard DWARF format.
 100 It should point to a location that will be set to 4 for normal
 101 objects and to 0 for non-standard ones.
 102 Argument
 103 .Ar cu_next_offset
 104 should point to a location that will be set to the
 105 offset of the next compilation unit header in the
 106 .Dq \&.debug_info
 107 section.
 108 Argument
 109 .Ar err
 110 should point to a location that will hold an error descriptor in case
 111 of an error.
 112 .Pp
 113 Function
 114 .Fn dwarf_next_cu_header
 115 is less general than
 116 .Fn dwarf_next_cu_header_b ,
 117 and is deprecated for use by new application code.
 118 Argument
 119 .Ar dbg
 120 should reference a DWARF debug context allocated using
 121 .Xr dwarf_init 3 .
 122 Argument
 123 .Ar cu_length
 124 should point to a location that will be set to the
 125 length of the compilation unit.
 126 Argument
 127 .Ar cu_version
 128 should point to a location that will be set to the
 129 version number for the compilation unit.
 130 Argument
 131 .Ar cu_abbrev_offset
 132 should point to a location that will be set to the
 133 starting offset in the
 134 .Dq .debug_abbrev
 135 section of the set of debugging information entry abbreviations
 136 associated with this compilation unit.
 137 Argument
 138 .Ar cu_pointer_size
 139 should point to a location that will be set to the
 140 size of an address in bytes for the machine architecture of the
 141 underlying debugging object.
 142 Argument
 143 .Ar cu_next_offset
 144 should point to a location that will be set to the
 145 offset of the next compilation unit.
 146 Argument
 147 .Ar err
 148 should point to a location that will hold an error descriptor in case
 149 of an error.
 150 .Pp
 151 A value of NULL may be used for any of the arguments
 152 .Ar cu_length ,
 153 .Ar cu_version ,
 154 .Ar cu_abbrev_offset ,
 155 .Ar cu_pointer_size ,
 156 .Ar cu_offset_size ,
 157 .Ar cu_extension_size ,
 158 .Ar cu_next_offset
 159 and
 160 .Ar err
 161 if the caller is not interested in the respective value.
 162 .Ss Iterating Through Compilation Units in a Debug Context
 163 .Pp
 164 The first call to functions
 165 .Fn dwarf_next_cu_header_b
 166 and
 167 .Fn dwarf_next_cu_header
 168 for a given debug context will return information about the first
 169 compilation unit in the debug context.
 170 Subsequent calls to these functions will iterate through the remaining
 171 compilation units in the debug context.
 172 On stepping past the last compilation unit in the debug context,
 173 functions
 174 .Fn dwarf_next_cu_header
 175 and
 176 .Fn dwarf_next_cu_header_b
 177 return
 178 .Dv DW_DLV_NO_ENTRY
 179 and reset their internal state.
 180 The next call to these functions will restart from the first compilation
 181 unit in the debug context.
 182 .Sh RETURN VALUES
 183 On success, these functions return
 184 .Dv DW_DLV_OK .
 185 In case of an error, they return
 186 .Dv DW_DLV_ERROR
 187 and set argument
 188 .Ar err .
 189 When there are no more compilation units left to traverse, they return
 190 .Dv DW_DLV_NO_ENTRY .
 191 .Sh ERRORS
 192 These functions can fail with the following error:
 193 .Bl -tag -width ".Bq Er DW_DLE_ARGUMENT"
 194 .It Bq Er DW_DLE_ARGUMENT
 195 Argument
 196 .Va dbg
 197 was NULL.
 198 .El
 199 .Sh SEE ALSO
 200 .Xr dwarf 3 ,
 201 .Xr dwarf_get_cu_die_offset_given_cu_header_offset 3 ,
 202 .Xr dwarf_init 3 ,
 203 .Xr dwarf_siblingof 3