1.\" $NetBSD: dwarf_loclist.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.3 2122 2011-11-09 15:35:14Z jkoshy 28.\" 29.Dd November 9, 2011 30.Os 31.Dt DWARF_LOCLIST 3 32.Sh NAME 33.Nm dwarf_loclist , 34.Nm dwarf_loclist_n 35.Nd retrieve DWARF location expression information 36.Sh LIBRARY 37.Lb libdwarf 38.Sh SYNOPSIS 39.In libdwarf.h 40.Ft int 41.Fo dwarf_loclist 42.Fa "Dwarf_Attribute at" 43.Fa "Dwarf_Locdesc **llbuf" 44.Fa "Dwarf_Signed *listlen" 45.Fa "Dwarf_Error *error" 46.Fc 47.Ft int 48.Fo dwarf_loclist_n 49.Fa "Dwarf_Attribute at" 50.Fa "Dwarf_Locdesc ***llbuf" 51.Fa "Dwarf_Signed *listlen" 52.Fa "Dwarf_Error *error" 53.Fc 54.Sh DESCRIPTION 55These functions retrieve the location expressions 56associated with a DWARF attribute. 57.Pp 58Note: function 59.Fn dwarf_loclist 60is deprecated. 61New application code should instead use function 62.Fn dwarf_loclist_n 63.Pp 64Function 65.Fn dwarf_loclist_n 66retrieves the list of location expressions associated with a DWARF 67attribute. 68Argument 69.Ar at 70should reference a valid DWARF attribute. 71Argument 72.Ar llbuf 73should point to a location which will hold a returned array of 74pointers to 75.Vt Dwarf_Locdesc 76descriptors. 77Argument 78.Ar listlen 79should point to a location which will be set to the number of 80elements contained in the returned array. 81If argument 82.Ar err 83is not NULL, it will be used to store error information in case 84of an error. 85.Pp 86Function 87.Fn dwarf_loclist 88retrieves the first location expression associated with an attribute. 89Argument 90.Ar at 91should reference a valid DWARF attribute. 92Argument 93.Ar llbuf 94should point to a location which will hold the returned pointer 95to a 96.Vt Dwarf_Locdesc 97descriptor. 98Argument 99.Ar listlen 100should point to a location which will be always set to 1. 101If argument 102.Ar err 103is not NULL, it will be used to store error information in case 104of an error. 105.Pp 106.Vt Dwarf_Locdesc 107descriptors are defined in the header file 108.In libdwarf.h , 109and consist of following fields: 110.Pp 111.Bl -tag -width ".Va ld_cents" -compact 112.It Va ld_lopc 113The lowest program counter address covered by the descriptor. 114This field will be set to 0 if the descriptor is not associated with 115an address range. 116.It Va ld_hipc 117The highest program counter address covered by the descriptor. 118This field will be set to 0 if the descriptor is not associated with 119an address range. 120.It Va ld_cents 121The number of entries returned in 122.Va ld_s 123field. 124.It Va ld_s 125Pointer to an array of 126.Vt Dwarf_Loc 127descriptors. 128.El 129.Pp 130Each 131.Vt Dwarf_Loc 132descriptor represents one operation of a location expression. 133These descriptors are defined in the header file 134.In libdwarf.h , 135and consist of following fields: 136.Pp 137.Bl -tag -width ".Va lr_number2" -compact 138.It Va lr_atom 139The operator name, one of the 140.Dv DW_OP_* 141constants defined in the header file 142.In dwarf.h . 143.It Va lr_number 144The first operand of this operation. 145.It Va lr_number2 146The second operand of this operation. 147.It Va lr_offset 148The byte offset of this operation within the containing location 149expression. 150.El 151.Ss Memory Management 152The memory area used for the descriptor array returned in argument 153.Ar llbuf 154is allocated by the 155.Lb libdwarf . 156When the descriptor array is no longer needed, application code should 157use function 158.Xr dwarf_dealloc 3 159to free the memory area in the following manner: 160.Bl -enum 161.It 162First, the 163.Ar ld_s 164field of each 165.Vt Dwarf_Locdesc 166descriptor should be deallocated using the allocation type 167.Dv DW_DLA_LOC_BLOCK . 168.It 169Then, the application should free each 170.Vt Dwarf_Locdesc 171descriptor using the allocation type 172.Dv DW_DLA_LOCDESC . 173.It 174Finally, the 175.Va llbuf 176pointer should be deallocated using the allocation type 177.Dv DW_DLA_LIST . 178.El 179.Sh RETURN VALUES 180On success, these functions returns 181.Dv DW_DLV_OK . 182In case of an error, they return 183.Dv DW_DLV_ERROR 184and set the argument 185.Ar err . 186.Sh ERRORS 187These functions can fail with: 188.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" 189.It Bq Er DW_DLE_ARGUMENT 190One of the arguments 191.Ar at , 192.Ar llbuf 193or 194.Ar listlen 195was NULL. 196.It Bq Er DW_DLE_ARGUMENT 197The attribute provided by argument 198.Ar at 199does not contain a location expression or is not associated with a 200location expression list. 201.El 202.Sh EXAMPLE 203To retrieve the location list associated with an attribute, use: 204.Bd -literal -offset indent 205Dwarf_Attribute at; 206Dwarf_Locdesc **llbuf; 207Dwarf_Signed lcnt; 208Dwarf_Loc *lr; 209Dwarf_Error de; 210int i; 211 212if (dwarf_loclist_n(at, &llbuf, &lcnt, &de) != DW_DLV_OK) 213 errx(EXIT_FAILURE, "dwarf_loclist_n failed: %s", 214 dwarf_errmsg(de)); 215 216for (i = 0; i < lcnt; i++) { 217 /* ... Use llbuf[i] ... */ 218 for (j = 0; (Dwarf_Half) j < llbuf[i]->ld_cents; j++) { 219 lr = &llbuf[i]->ld_s[j]; 220 /* ... Use each Dwarf_Loc descriptor ... */ 221 } 222 dwarf_dealloc(dbg, llbuf[i]->ld_s, DW_DLA_LOC_BLOCK); 223 dwarf_dealloc(dbg, llbuf[i], DW_DLA_LOCDESC); 224} 225dwarf_dealloc(dbg, llbuf, DW_DLA_LIST); 226.Ed 227.Sh SEE ALSO 228.Xr dwarf 3 , 229.Xr dwarf_dealloc 3 , 230.Xr dwarf_loclist_from_expr 3 , 231.Xr dwarf_loclist_from_expr_a 3 , 232.Xr dwarf_get_loclist_entry 3 233