contrib/elftoolchain/libdwarf/dwarf_get_vars.3

   1 .\" Copyright (c) 2011 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_get_vars.3 3640 2018-10-14 14:09:13Z jkoshy $
  26 .\"
  27 .Dd April 2, 2011
  28 .Dt DWARF_GET_VARS 3
  29 .Os
  30 .Sh NAME
  31 .Nm dwarf_get_vars ,
  32 .Nm dwarf_var_cu_offset ,
  33 .Nm dwarf_var_die_offset ,
  34 .Nm dwarf_var_name_offsets ,
  35 .Nm dwarf_varname
  36 .Nd retrieve information about static variables
  37 .Sh LIBRARY
  38 .Lb libdwarf
  39 .Sh SYNOPSIS
  40 .In libdwarf.h
  41 .Ft int
  42 .Fo dwarf_get_vars
  43 .Fa "Dwarf_Debug dbg"
  44 .Fa "Dwarf_Var **vars"
  45 .Fa "Dwarf_Signed *nvars"
  46 .Fa "Dwarf_Error *err"
  47 .Fc
  48 .Ft int
  49 .Fo dwarf_var_cu_offset
  50 .Fa "Dwarf_Var var"
  51 .Fa "Dwarf_Off *cu_offset"
  52 .Fa "Dwarf_Error *err"
  53 .Fc
  54 .Ft int
  55 .Fo dwarf_var_die_offset
  56 .Fa "Dwarf_Var var"
  57 .Fa "Dwarf_Off *die_offset"
  58 .Fa "Dwarf_Error *err"
  59 .Fc
  60 .Ft int
  61 .Fo dwarf_var_name_offsets
  62 .Fa "Dwarf_Var var"
  63 .Fa "char **name"
  64 .Fa "Dwarf_Off *die_offset"
  65 .Fa "Dwarf_Off *cu_die_offset"
  66 .Fa "Dwarf_Error *err"
  67 .Fc
  68 .Ft int
  69 .Fo dwarf_varname
  70 .Fa "Dwarf_Var var"
  71 .Fa "char **name"
  72 .Fa "Dwarf_Error *err"
  73 .Fc
  74 .Sh DESCRIPTION
  75 These functions retrieve information about the file scope static
  76 variables associated with a DWARF debug context.
  77 Information about these static variables is returned using opaque
  78 descriptors of type
  79 .Vt Dwarf_Var .
  80 Applications need to use the functions described below to retrieve
  81 the name and offset information contained in these descriptors.
  82 .Pp
  83 Function
  84 .Fn dwarf_get_vars
  85 retrieves descriptors for all the static variables associated with the
  86 DWARF debug context specified by argument
  87 .Ar dbg .
  88 The argument
  89 .Ar vars
  90 should point to a location that will be set to a pointer to an array
  91 of
  92 .Vt Dwarf_Var
  93 descriptors.
  94 The argument
  95 .Ar nvars
  96 should point to a location that will be set to the number of
  97 descriptors returned.
  98 .Pp
  99 Function
 100 .Fn dwarf_var_cu_offset
 101 returns the section-relative offset, relative to the
 102 .Dq ".debug_info"
 103 section, of the compilation unit that
 104 contains the debugging information entry associated with the argument
 105 .Ar var .
 106 Argument
 107 .Ar cu_offset
 108 should point to a location that will hold the returned offset.
 109 .Pp
 110 Function
 111 .Fn dwarf_var_die_offset
 112 retrieves the section-relative offset, relative to the
 113 .Dq ".debug_info"
 114 section, of the debugging information
 115 entry associated with the argument
 116 .Ar var ,
 117 and stores it into the location pointed to by the argument
 118 .Ar die_offset .
 119 .Pp
 120 Function
 121 .Fn dwarf_var_name_offsets
 122 retrieves both the name and the associated offsets for the debugging
 123 information entry for argument
 124 .Ar var .
 125 Argument
 126 .Ar name
 127 should point to a location which will be set to a pointer to a
 128 NUL-terminated string containing the name of the associated debugging
 129 information entry.
 130 Argument
 131 .Ar die_offset
 132 should point to a location which will be set to a section-relative
 133 offset, relative to the
 134 .Dq ".debug_info"
 135 section, of the associated debugging information entry.
 136 Argument
 137 .Ar cu_die_offset
 138 should point to a location which will be set to a
 139 section-relative offset, relative to the
 140 .Dq ".debug_info"
 141 section, of the first debugging information entry in
 142 the compilation unit associated with argument
 143 .Ar var .
 144 .Pp
 145 Function
 146 .Fn dwarf_varname
 147 sets the location pointed to by argument
 148 .Ar name
 149 to a pointer to a NUL-terminated string holding the name of the
 150 debugging information entry associated with the argument
 151 .Ar var .
 152 .Ss Memory Management
 153 The memory area used for the array of
 154 .Vt Dwarf_Var
 155 descriptors returned in argument
 156 .Ar vars
 157 by function
 158 .Fn dwarf_get_vars
 159 is owned by the
 160 .Lb libdwarf .
 161 Application code should not attempt to directly free this pointer.
 162 Portable code should instead use the function
 163 .Xr dwarf_vars_dealloc 3
 164 to indicate that the memory area may be freed.
 165 .Pp
 166 The memory area used for the string returned in the
 167 .Ar name
 168 argument to functions
 169 .Fn dwarf_var_name_offsets
 170 and
 171 .Fn dwarf_varname
 172 is owned by the
 173 .Lb libdwarf .
 174 Portable code should indicate that the memory area can
 175 be freed using the
 176 .Xr dwarf_dealloc 3
 177 function.
 178 .Ss Error Returns
 179 If argument
 180 .Ar err
 181 is not NULL, these functions will use it to store error information,
 182 in case of an error.
 183 .Sh RETURN VALUES
 184 On success, these functions returns
 185 .Dv DW_DLV_OK .
 186 In case of an error, they return
 187 .Dv DW_DLV_ERROR
 188 and set the argument
 189 .Ar err .
 190 .Sh ERRORS
 191 These functions may fail with the following errors:
 192 .Bl -tag -width ".Bq Er DW_DLE_ARGUMENT"
 193 .It Bq Er DW_DLE_ARGUMENT
 194 One of the arguments
 195 .Va cu_die_offset ,
 196 .Va cu_offset ,
 197 .Va dbg ,
 198 .Va die_offset ,
 199 .Va var ,
 200 .Va vars ,
 201 .Va name ,
 202 or
 203 .Va nvars
 204 was NULL.
 205 .El
 206 .Sh SEE ALSO
 207 .Xr dwarf 3 ,
 208 .Xr dwarf_dealloc 3 ,
 209 .Xr dwarf_get_cu_die_offset_given_cu_header_offset 3 ,
 210 .Xr dwarf_vars_dealloc 3