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