contrib/elftoolchain/libdwarf/dwarf_get_loclist_entry.3

   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
  49 Function
  50 .Fn dwarf_get_loclist_entry
  51 retrieves a location list entry from the DWARF section
  52 .Dq ".debug_loc" .
  53 .Pp
  54 Argument
  55 .Ar dbg
  56 should reference a DWARF debug context allocated using
  57 .Xr dwarf_init 3 .
  58 .Pp
  59 Argument
  60 .Ar offset
  61 is an offset, relative to the
  62 .Dq ".debug_loc"
  63 section, to the start of the desired location list entry.
  64 .Pp
  65 Argument
  66 .Ar hipc
  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.
  70 .Pp
  71 Argument
  72 .Ar lowpc
  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
  75 value for the entry.
  76 .Pp
  77 Argument
  78 .Ar data
  79 should point to a location which will be set to a pointer to the location
  80 list data.
  81 .Pp
  82 Argument
  83 .Ar entry_len
  84 should point to a location which will hold the length in bytes of the
  85 location list data returned in argument
  86 .Ar data .
  87 .Pp
  88 Argument
  89 .Ar next_entry
  90 should point to a location which will hold the offset of the next
  91 location list entry.
  92 .Pp
  93 If argument
  94 .Ar err
  95 is not NULL, it will be used to store error information in case
  96 of an error.
  97 .Sh RETURN VALUES
  98 Function
  99 .Fn dwarf_get_loclist_entry
 100 returns
 101 .Dv DW_DLV_OK
 102 when it succeeds.
 103 It returns
 104 .Dv DW_DLV_NO_ENTRY
 105 if there is no location list at the specified offset
 106 .Ar offset .
 107 In case of an error, it returns
 108 .Dv DW_DLV_ERROR
 109 and sets the argument
 110 .Ar err .
 111 .Sh EXAMPLES
 112 To iterate through all the location list entries in the
 113 .Dq ".debug_loc"
 114 section, use:
 115 .Bd -literal -offset indent
 116 Dwarf_Debug dbg;
 117 Dwarf_Unsigned off, len, next;
 118 Dwarf_Addr hipc, lopc;
 119 Dwarf_Ptr data;
 120 Dwarf_Error de;
 121 int ret;
 122
 123 off = 0;
 124 while ((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 }
 129 if (ret == DW_DLV_ERROR)
 130         warnx("dwarf_get_loclist_entry failed: %s", dwarf_errmsg(de));
 131 .Ed
 132 .Sh ERRORS
 133 Function
 134 .Fn dwarf_get_loclist_entry
 135 can fail with:
 136 .Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY"
 137 .It Bq Er DW_DLE_ARGUMENT
 138 One of the arguments
 139 .Ar dbg ,
 140 .Ar hipc ,
 141 .Ar lopc ,
 142 .Ar data ,
 143 .Ar entry_len
 144 or
 145 .Ar next_entry
 146 was NULL.
 147 .It Bq Er DW_DLE_NO_ENTRY
 148 There 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