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 75These functions retrieve information about the file scope static 76variables associated with a DWARF debug context. 77Information about these static variables is returned using opaque 78descriptors of type 79.Vt Dwarf_Var . 80Applications need to use the functions described below to retrieve 81the name and offset information contained in these descriptors. 82.Pp 83Function 84.Fn dwarf_get_vars 85retrieves descriptors for all the static variables associated with the 86DWARF debug context specified by argument 87.Ar dbg . 88The argument 89.Ar vars 90should point to a location that will be set to a pointer to an array 91of 92.Vt Dwarf_Var 93descriptors. 94The argument 95.Ar nvars 96should point to a location that will be set to the number of 97descriptors returned. 98.Pp 99Function 100.Fn dwarf_var_cu_offset 101returns the section-relative offset, relative to the 102.Dq ".debug_info" 103section, of the compilation unit that 104contains the debugging information entry associated with the argument 105.Ar var . 106Argument 107.Ar cu_offset 108should point to a location that will hold the returned offset. 109.Pp 110Function 111.Fn dwarf_var_die_offset 112retrieves the section-relative offset, relative to the 113.Dq ".debug_info" 114section, of the debugging information 115entry associated with the argument 116.Ar var , 117and stores it into the location pointed to by the argument 118.Ar die_offset . 119.Pp 120Function 121.Fn dwarf_var_name_offsets 122retrieves both the name and the associated offsets for the debugging 123information entry for argument 124.Ar var . 125Argument 126.Ar name 127should point to a location which will be set to a pointer to a 128NUL-terminated string containing the name of the associated debugging 129information entry. 130Argument 131.Ar die_offset 132should point to a location which will be set to a section-relative 133offset, relative to the 134.Dq ".debug_info" 135section, of the associated debugging information entry. 136Argument 137.Ar cu_die_offset 138should point to a location which will be set to a 139section-relative offset, relative to the 140.Dq ".debug_info" 141section, of the first debugging information entry in 142the compilation unit associated with argument 143.Ar var . 144.Pp 145Function 146.Fn dwarf_varname 147sets the location pointed to by argument 148.Ar name 149to a pointer to a NUL-terminated string holding the name of the 150debugging information entry associated with the argument 151.Ar var . 152.Ss Memory Management 153The memory area used for the array of 154.Vt Dwarf_Var 155descriptors returned in argument 156.Ar vars 157by function 158.Fn dwarf_get_vars 159is owned by the 160.Lb libdwarf . 161Application code should not attempt to directly free this pointer. 162Portable code should instead use the function 163.Xr dwarf_vars_dealloc 3 164to indicate that the memory area may be freed. 165.Pp 166The memory area used for the string returned in the 167.Ar name 168argument to functions 169.Fn dwarf_var_name_offsets 170and 171.Fn dwarf_varname 172is owned by the 173.Lb libdwarf . 174Portable code should indicate that the memory area can 175be freed using the 176.Xr dwarf_dealloc 3 177function. 178.Ss Error Returns 179If argument 180.Ar err 181is not NULL, these functions will use it to store error information, 182in case of an error. 183.Sh RETURN VALUES 184On success, these functions returns 185.Dv DW_DLV_OK . 186In case of an error, they return 187.Dv DW_DLV_ERROR 188and set the argument 189.Ar err . 190.Sh ERRORS 191These functions may fail with the following errors: 192.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" 193.It Bq Er DW_DLE_ARGUMENT 194One 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 , 202or 203.Va nvars 204was 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 211