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