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_get_loclist_entry.3 3644 2018-10-15 19:55:01Z jkoshy $ 26.\" 27.Dd July 6, 2011 28.Dt DWARF_GET_LOCLIST_ENTRY 3 29.Os 30.Sh NAME 31.Nm dwarf_get_loclist_entry 32.Nd retrieve DWARF location list entry 33.Sh LIBRARY 34.Lb libdwarf 35.Sh SYNOPSIS 36.In libdwarf.h 37.Ft int 38.Fo dwarf_get_loclist_entry 39.Fa "Dwarf_Debug dbg" 40.Fa "Dwarf_Unsigned offset" 41.Fa "Dwarf_Addr *hipc" 42.Fa "Dwarf_Addr *lopc" 43.Fa "Dwarf_Ptr *data" 44.Fa "Dwarf_Unsigned *entry_len" 45.Fa "Dwarf_Unsigned *next_entry" 46.Fa "Dwarf_Error *err" 47.Fc 48.Sh DESCRIPTION 49Function 50.Fn dwarf_get_loclist_entry 51retrieves a location list entry from the DWARF section 52.Dq ".debug_loc" . 53.Pp 54Argument 55.Ar dbg 56should reference a DWARF debug context allocated using 57.Xr dwarf_init 3 . 58.Pp 59Argument 60.Ar offset 61is an offset, relative to the 62.Dq ".debug_loc" 63section, to the start of the desired location list entry. 64.Pp 65Argument 66.Ar hipc 67should point to a location which will hold the offset, relative to the 68base address of the location list entry, of the highest program 69counter value for the entry. 70.Pp 71Argument 72.Ar lowpc 73should point to a location which will hold the offset, relative to the 74base address of the location list entry, of the lowest program counter 75value for the entry. 76.Pp 77Argument 78.Ar data 79should point to a location which will be set to a pointer to the location 80list data. 81.Pp 82Argument 83.Ar entry_len 84should point to a location which will hold the length in bytes of the 85location list data returned in argument 86.Ar data . 87.Pp 88Argument 89.Ar next_entry 90should point to a location which will hold the offset of the next 91location list entry. 92.Pp 93If argument 94.Ar err 95is not NULL, it will be used to store error information in case 96of an error. 97.Sh RETURN VALUES 98Function 99.Fn dwarf_get_loclist_entry 100returns 101.Dv DW_DLV_OK 102when it succeeds. 103It returns 104.Dv DW_DLV_NO_ENTRY 105if there is no location list at the specified offset 106.Ar offset . 107In case of an error, it returns 108.Dv DW_DLV_ERROR 109and sets the argument 110.Ar err . 111.Sh EXAMPLES 112To iterate through all the location list entries in the 113.Dq ".debug_loc" 114section, use: 115.Bd -literal -offset indent 116Dwarf_Debug dbg; 117Dwarf_Unsigned off, len, next; 118Dwarf_Addr hipc, lopc; 119Dwarf_Ptr data; 120Dwarf_Error de; 121int ret; 122 123off = 0; 124while ((ret = dwarf_get_loclist_entry(dbg, off, &hipc, &lopc, &data, 125 &len, &next, &de)) == DW_DLV_OK) { 126 /* ... use loclist entry ... */ 127 off = next; 128} 129if (ret == DW_DLV_ERROR) 130 warnx("dwarf_get_loclist_entry failed: %s", dwarf_errmsg(de)); 131.Ed 132.Sh ERRORS 133Function 134.Fn dwarf_get_loclist_entry 135can fail with: 136.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" 137.It Bq Er DW_DLE_ARGUMENT 138One of the arguments 139.Ar dbg , 140.Ar hipc , 141.Ar lopc , 142.Ar data , 143.Ar entry_len 144or 145.Ar next_entry 146was NULL. 147.It Bq Er DW_DLE_NO_ENTRY 148There is no location list at the specified offset 149.Ar offset . 150.El 151.Sh SEE ALSO 152.Xr dwarf 3 , 153.Xr dwarf_loclist 3 , 154.Xr dwarf_loclist_from_expr 3 , 155.Xr dwarf_loclist_from_expr_a 3 , 156.Xr dwarf_loclist_n 3 157