1.\" Copyright (c) 2011,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_loclist_from_expr.3 3644 2018-10-15 19:55:01Z jkoshy $ 26.\" 27.Dd December 21, 2014 28.Dt DWARF_LOCLIST_FROM_EXPR 3 29.Os 30.Sh NAME 31.Nm dwarf_loclist_from_expr , 32.Nm dwarf_loclist_from_expr_a , 33.Nm dwarf_loclist_from_expr_b 34.Nd translate DWARF location expression bytes 35.Sh LIBRARY 36.Lb libdwarf 37.Sh SYNOPSIS 38.In libdwarf.h 39.Ft int 40.Fo dwarf_loclist_from_expr 41.Fa "Dwarf_Debug dbg" 42.Fa "Dwarf_Ptr bytes_in" 43.Fa "Dwarf_Unsigned bytes_len" 44.Fa "Dwarf_Locdesc **llbuf" 45.Fa "Dwarf_Signed *listlen" 46.Fa "Dwarf_Error *err" 47.Fc 48.Ft int 49.Fo dwarf_loclist_from_expr_a 50.Fa "Dwarf_Debug dbg" 51.Fa "Dwarf_Ptr bytes_in" 52.Fa "Dwarf_Unsigned bytes_len" 53.Fa "Dwarf_Half addr_size" 54.Fa "Dwarf_Locdesc **llbuf" 55.Fa "Dwarf_Signed *listlen" 56.Fa "Dwarf_Error *err" 57.Fc 58.Ft int 59.Fo dwarf_loclist_from_expr_b 60.Fa "Dwarf_Debug dbg" 61.Fa "Dwarf_Ptr bytes_in" 62.Fa "Dwarf_Unsigned bytes_len" 63.Fa "Dwarf_Half addr_size" 64.Fa "Dwarf_Half offset_size" 65.Fa "Dwarf_Small version" 66.Fa "Dwarf_Locdesc **llbuf" 67.Fa "Dwarf_Signed *listlen" 68.Fa "Dwarf_Error *error" 69.Fc 70.Sh DESCRIPTION 71Function 72.Fn dwarf_loclist_from_expr 73translates DWARF location expression bytes into a 74.Vt Dwarf_Locdesc 75descriptor. 76The size for address related data is taken to be the default address 77size for the object being read. 78.Pp 79Argument 80.Ar dbg 81should reference a DWARF debug context allocated using 82.Xr dwarf_init 3 . 83.Pp 84Argument 85.Ar bytes_in 86should point to an array of DWARF location expression bytes. 87.Pp 88Argument 89.Ar bytes_len 90should specify the number of the location expression bytes to be 91translated. 92.Pp 93Argument 94.Ar llbuf 95should point to a location which will be set to a pointer 96to a returned 97.Vt Dwarf_Locdesc 98descriptor. 99.Pp 100Argument 101.Ar listlen 102should point to a location which will hold the number of the 103.Vt Dwarf_Locdesc 104descriptors returned. 105In this case it is always set to 1. 106.Pp 107If argument 108.Ar err 109is not NULL, it will be used to store error information in case of an 110error. 111.Pp 112Function 113.Fn dwarf_loclist_from_expr_a 114is identical to function 115.Fn dwarf_loclist_from_expr , 116except that it requires one additional argument 117.Ar addr_size , 118which specifies the address size to use when translating the location 119expression bytes. 120.Pp 121Function 122.Fn dwarf_loclist_from_expr_b 123is identical to function 124.Fn dwarf_loclist_from_expr_a 125except that it requires two additional arguments for translating the 126location expression bytes. 127Argument 128.Ar offset_size 129specifies the offset size, and argument 130.Ar version 131specifies the DWARF version. 132These values are required to correctly translate the 133.Dv DW_OP_GNU_implicit_pointer 134opcode. 135.Ss Memory Management 136The memory area used for the descriptor returned in argument 137.Ar llbuf 138is allocated by 139.Lb libdwarf . 140When the descriptor is no longer needed, application code should use 141function 142.Xr dwarf_dealloc 3 143to free the memory area in two steps: 144.Bl -enum -compact 145.It 146First, the array of 147.Vt Dwarf_Loc 148descriptors pointed to by the 149.Ar ld_s 150field of the 151.Vt Dwarf_Locdesc 152descriptor should be deallocated using the allocation type 153.Dv DW_DLA_LOC_BLOCK . 154.It 155Next, the application should free the 156.Ar llbuf 157pointer using the allocation type 158.Dv DW_DLA_LOCDESC . 159.El 160.Sh RETURN VALUES 161On success, these functions returns 162.Dv DW_DLV_OK . 163In case of an error, they return 164.Dv DW_DLV_ERROR 165and set the argument 166.Ar err . 167.Sh ERRORS 168These functions may fail with the following errors: 169.Bl -tag -width ".Bq Er DW_DLE_LOC_EXPR_BAD" 170.It Bq Er DW_DLE_ARGUMENT 171One of the arguments 172.Va dbg , 173.Va bytes_in , 174.Va llbuf 175or 176.Va listlen 177was NULL. 178.It Bq Er DW_DLE_ARGUMENT 179Argument 180.Ar bytes_len 181was 0. 182.It Bq Er DW_DLE_ARGUMENT 183The value of argument 184.Ar addr_size 185was invalid. 186.It Bq Er DW_DLE_LOC_EXPR_BAD 187An unknown or invalid operation was found in the location expression 188bytes provided in argument 189.Ar bytes_in . 190.It Bq Er DW_DLE_MEMORY 191An out of memory condition was encountered during the execution of 192this function. 193.El 194.Sh SEE ALSO 195.Xr dwarf 3 , 196.Xr dwarf_dealloc 3 , 197.Xr dwarf_get_fde_info_for_all_regs3 3 , 198.Xr dwarf_get_fde_info_for_cfa_reg3 3 , 199.Xr dwarf_get_fde_info_for_reg3 3 , 200.Xr dwarf_get_loclist_entry 3 , 201.Xr dwarf_loclist_n 3 202