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