contrib/elftoolchain/libdwarf/dwarf_get_relocation_info.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_relocation_info.3 3644 2018-10-15 19:55:01Z jkoshy $
  26 .\"
  27 .Dd September 3, 2011
  28 .Dt DWARF_GET_RELOCATION_INFO 3
  29 .Os
  30 .Sh NAME
  31 .Nm dwarf_get_relocation_info
  32 .Nd retrieve generated relocation arrays
  33 .Sh LIBRARY
  34 .Lb libdwarf
  35 .Sh SYNOPSIS
  36 .In libdwarf.h
  37 .Ft int
  38 .Fo dwarf_get_relocation_info
  39 .Fa "Dwarf_P_Debug dbg"
  40 .Fa "Dwarf_Signed *elf_section_index"
  41 .Fa "Dwarf_Signed *elf_section_link"
  42 .Fa "Dwarf_Unsigned *reloc_entry_count"
  43 .Fa "Dwarf_Relocation_Data *reloc_buf"
  44 .Fa "Dwarf_Error *err"
  45 .Fc
  46 .Sh DESCRIPTION
  47 The function
  48 .Fn dwarf_get_relocation_info
  49 is used to retrieve the relocation arrays generated by a prior call to
  50 .Xr dwarf_transform_to_disk_form 3 .
  51 .Pp
  52 Each call to this function retrieves the next available relocation
  53 array.
  54 Application code should call this function repeatly to retrieve all
  55 the relocation arrays.
  56 The total number of generated relocation arrays retrievable
  57 by this function may be obtained by calling function
  58 .Xr dwarf_get_relocation_info_count 3 .
  59 .Pp
  60 Argument
  61 .Ar dbg
  62 should reference a DWARF producer instance allocated using
  63 .Xr dwarf_producer_init 3 in sequence.
  64 or
  65 .Xr dwarf_producer_init_b 3 .
  66 The
  67 .Dv DW_DLC_SYMBOLIC_RELOCATIONS
  68 flag should have been set on the DWARF producer instance.
  69 .Pp
  70 Argument
  71 .Ar elf_section_index
  72 should point to a location which will be set to the ELF section index
  73 of the relocation section to which the retrieved relocation array
  74 belongs.
  75 .Pp
  76 Argument
  77 .Ar elf_section_link
  78 should point to a location which will be set to the section index of
  79 the ELF section to which the retrieved relocation array applies.
  80 .Pp
  81 Argument
  82 .Ar reloc_entry_count
  83 should point to a location which will be set to the total number of
  84 relocation entries contained in the relocation array.
  85 .Pp
  86 Argument
  87 .Ar reloc_buf
  88 should point to a location which will be set to a pointer to the
  89 retrieved array of relocation entries.
  90 .Pp
  91 If argument
  92 .Ar err
  93 is not NULL, it will be used to store error information in case
  94 of an error.
  95 .Pp
  96 The retrieved relocation entries are described using structure
  97 .Vt Dwarf_Relocation_Data_s ,
  98 defined in the header file
  99 .In libdwarf.h :
 100 .Bd -literal -offset indent
 101 typedef struct Dwarf_Relocation_Data_s {
 102         unsigned char drd_type;
 103         unsigned char drd_length;
 104         Dwarf_Unsigned drd_offset;
 105         Dwarf_Unsigned drd_symbol_index;
 106 } *Dwarf_Relocation_Data;
 107 .Ed
 108 .Pp
 109 Struct
 110 .Vt Dwarf_Relocation_Data_s
 111 consists of following fields:
 112 .Bl -tag -width ".Va drd_symbol_index" -compact -offset indent
 113 .It Va drd_type
 114 The type code of the relocation entry.
 115 The
 116 .Vt Dwarf_Rel_Type
 117 enumeration defined in the header file
 118 .In libdwarf.h
 119 specifies legal values for this field.
 120 .It Va drd_length
 121 The size in bytes of the field to be relocated.
 122 .It Va drd_offset
 123 The section-relative offset of the field to be relocated.
 124 .It Va drd_symbol_index
 125 The symbol index associated with the relocation entry.
 126 .El
 127 .Ss Memory Management
 128 The memory area used for the relocation arrays is managed by the
 129 .Lb libdwarf .
 130 The function
 131 .Fn dwarf_producer_finish
 132 may be used to release it, along with other resources associated
 133 with the producer instance.
 134 .Sh RETURN VALUES
 135 On success, function
 136 .Fn dwarf_get_relocation_info
 137 returns
 138 .Dv DW_DLV_OK .
 139 It returns
 140 .Dv DW_DLV_NO_ENTRY
 141 if there were no more relocation arrays to retrieve, or if the flag
 142 .Dv DW_DLC_SYMBOLIC_RELOCATIONS
 143 was not set on the producer instance.
 144 In case of an error, function
 145 .Fn dwarf_get_relocation_info
 146 returns
 147 .Dv DW_DLV_ERROR
 148 and sets the argument
 149 .Ar err .
 150 .Sh EXAMPLES
 151 To generate relocation entries and retrieve them, use:
 152 .Bd -literal -offset indent
 153 Dwarf_P_Debug dbg;
 154 Dwarf_Relocation_Data buf;
 155 Dwarf_Signed count, index, link;
 156 Dwarf_Unsigned reloc_cnt, entry_cnt;
 157 Dwarf_Error de;
 158 int version, i, j;
 159
 160 /*
 161  * Assume that dbg refers to a DWARF producer instance created
 162  * created with DW_DLC_SYMBOLIC_RELOCATIONS flag set and that
 163  * application code has added DWARF debugging information
 164  * to the producer instance.
 165  */
 166 if ((count = dwarf_transform_to_disk_form(dbg, &de)) ==
 167     DW_DLV_NOCOUNT) {
 168         warnx("dwarf_transform_to_disk_form failed: %s",
 169             dwarf_errmsg(-1));
 170         return;
 171 }
 172
 173 /* ... process generated section byte streams ... */
 174 if (dwarf_get_relocation_info_count(dbg, &reloc_cnt, &version, &de) !=
 175     DW_DLV_OK) {
 176         warnx("dwarf_get_relocation_info_count failed: %s",
 177             dwarf_errmsg(-1));
 178         return;
 179 }
 180
 181 for (i = 0; (Dwarf_Unsigned) i < reloc_cnt; i++) {
 182         if (dwarf_get_relocation_info(dbg, &index, &link, &entry_cnt,
 183             &buf, &de) != DW_DLV_OK) {
 184                 warnx("dwarf_get_relocation_info failed: %s",
 185                     dwarf_errmsg(-1));
 186                 continue;
 187         }
 188         for (j = 0; (Dwarf_Unsigned) j < entry_cnt; j++) {
 189                 /* ...use each reloc data in buf[j]... */
 190         }
 191 }
 192
 193 dwarf_producer_finish(dbg, &de);
 194 .Ed
 195 .Sh ERRORS
 196 Function
 197 .Fn dwarf_get_relocation_info
 198 can fail with:
 199 .Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY"
 200 .It Bq Er DW_DLE_ARGUMENT
 201 One of the arguments
 202 .Ar dbg ,
 203 .Ar elf_section_index ,
 204 .Ar elf_section_link ,
 205 .Ar reloc_entry_count
 206 or
 207 .Ar reloc_buf
 208 was NULL.
 209 .It Bq Er DW_DLE_NO_ENTRY
 210 There were no more ELF relocation arrays to retrieve.
 211 .It Bq Er DW_DLE_NO_ENTRY
 212 The flag
 213 .Dv DW_DLC_SYMBOLIC_RELOCATIONS
 214 was not set on the producer instance.
 215 .It Bq Er DW_DLE_NO_ENTRY
 216 Function
 217 .Xr dwarf_transform_to_disk_form 3
 218 was not called prior to calling function
 219 .Fn dwarf_get_relocation_info .
 220 .El
 221 .Sh SEE ALSO
 222 .Xr dwarf 3 ,
 223 .Xr dwarf_get_relocation_info_count 3 ,
 224 .Xr dwarf_producer_finish 3 ,
 225 .Xr dwarf_producer_init 3 ,
 226 .Xr dwarf_producer_init_b 3 ,
 227 .Xr dwarf_reset_section_bytes 3 ,
 228 .Xr dwarf_transform_to_disk_form 3