external/bsd/elftoolchain/dist/libdwarf/dwarf_next_cu_header.3

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