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