1 .\" Copyright (c) 2011 Kai Wang
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
25 .\" $Id: dwarf_get_loclist_entry.3 2071 2011-10-27 03:20:00Z jkoshy $
29 .Dt DWARF_GET_LOCLIST_ENTRY 3
31 .Nm dwarf_get_loclist_entry
32 .Nd retrieve DWARF location list entry
38 .Fo dwarf_get_loclist_entry
40 .Fa "Dwarf_Unsigned offset"
41 .Fa "Dwarf_Addr *hipc"
42 .Fa "Dwarf_Addr *lopc"
44 .Fa "Dwarf_Unsigned *entry_len"
45 .Fa "Dwarf_Unsigned *next_entry"
46 .Fa "Dwarf_Error *err"
50 .Fn dwarf_get_loclist_entry
51 retrieves a location list entry from the DWARF section
56 should reference a DWARF debug context allocated using
61 is an offset, relative to the
63 section, to the start of the desired location list entry.
67 should point to a location which will hold the offset, relative to the
68 base address of the location list entry, of the highest program
69 counter value for the entry.
73 should point to a location which will hold the offset, relative to the
74 base address of the location list entry, of the lowest program counter
79 should point to a location which will be set to a pointer to the location
84 should point to a location which will hold the length in bytes of the
85 location list data returned in argument
90 should point to a location which will hold the offset of the next
95 is not NULL, it will be used to store error information in case
99 .Fn dwarf_get_loclist_entry
105 if there is no location list at the specified offset
107 In case of an error, it returns
109 and sets the argument
113 .Fn dwarf_get_loclist_entry
115 .Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY"
116 .It Bq Er DW_DLE_ARGUMENT
126 .It Bq Er DW_DLE_NO_ENTRY
127 There is no location list at the specified offset
131 To iterate through all the location list entries in the
134 .Bd -literal -offset indent
136 Dwarf_Unsigned off, len, next;
137 Dwarf_Addr hipc, lopc;
143 while ((ret = dwarf_get_loclist_entry(dbg, off, &hipc, &lopc, &data,
144 &len, &next, &de)) == DW_DLV_OK) {
145 /* ... use loclist entry ... */
148 if (ret == DW_DLV_ERROR)
149 warnx("dwarf_get_loclist_entry failed: %s", dwarf_errmsg(de));
153 .Xr dwarf_loclist 3 ,
154 .Xr dwarf_loclist_n 3 ,
155 .Xr dwarf_loclist_from_expr 3 ,
156 .Xr dwarf_loclist_from_expr_a 3