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 2071 2011-10-27 03:20:00Z jkoshy $
  26 .\"
  27 .Dd September 3, 2011
  28 .Os
  29 .Dt DWARF_GET_RELOCATION_INFO 3
  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 ERRORS
 151 Function
 152 .Fn dwarf_get_relocation_info
 153 can fail with:
 154 .Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY"
 155 .It Bq Er DW_DLE_ARGUMENT
 156 One of the arguments
 157 .Ar dbg ,
 158 .Ar elf_section_index ,
 159 .Ar elf_section_link ,
 160 .Ar reloc_entry_count
 161 or
 162 .Ar reloc_buf
 163 was NULL.
 164 .It Bq Er DW_DLE_NO_ENTRY
 165 There were no more ELF relocation arrays to retrieve.
 166 .It Bq Er DW_DLE_NO_ENTRY
 167 The flag
 168 .Dv DW_DLC_SYMBOLIC_RELOCATIONS
 169 was not set on the producer instance.
 170 .It Bq Er DW_DLE_NO_ENTRY
 171 Function
 172 .Xr dwarf_transform_to_disk_form 3
 173 was not called prior to calling function
 174 .Fn dwarf_get_relocation_info .
 175 .El
 176 .Sh EXAMPLES
 177 To generate relocation entries and retrieve them, use:
 178 .Bd -literal -offset indent
 179 Dwarf_P_Debug dbg;
 180 Dwarf_Relocation_Data buf;
 181 Dwarf_Signed count, index, link;
 182 Dwarf_Unsigned reloc_cnt, entry_cnt;
 183 Dwarf_Error de;
 184 int version, i, j;
 185
 186 /*
 187  * Assume that dbg refers to a DWARF producer instance created
 188  * created with DW_DLC_SYMBOLIC_RELOCATIONS flag set and that
 189  * application code has added DWARF debugging information
 190  * to the producer instance.
 191  */
 192 if ((count = dwarf_transform_to_disk_form(dbg, &de)) ==
 193     DW_DLV_NOCOUNT) {
 194         warnx("dwarf_transform_to_disk_form failed: %s",
 195             dwarf_errmsg(-1));
 196         return;
 197 }
 198
 199 /* ... process generated section byte streams ... */
 200 if (dwarf_get_relocation_info_count(dbg, &reloc_cnt, &version, &de) !=
 201     DW_DLV_OK) {
 202         warnx("dwarf_get_relocation_info_count failed: %s",
 203             dwarf_errmsg(-1));
 204         return;
 205 }
 206
 207 for (i = 0; (Dwarf_Unsigned) i < reloc_cnt; i++) {
 208         if (dwarf_get_relocation_info(dbg, &index, &link, &entry_cnt,
 209             &buf, &de) != DW_DLV_OK) {
 210                 warnx("dwarf_get_relocation_info failed: %s",
 211                     dwarf_errmsg(-1));
 212                 continue;
 213         }
 214         for (j = 0; (Dwarf_Unsigned) j < entry_cnt; j++) {
 215                 /* ...use each reloc data in buf[j]... */
 216         }
 217 }
 218
 219 dwarf_producer_finish(dbg, &de);
 220 .Ed
 221 .Sh SEE ALSO
 222 .Xr dwarf 3 ,
 223 .Xr dwarf_get_relocation_info_count 3 ,
 224 .Xr dwarf_reset_section_bytes 3 ,
 225 .Xr dwarf_producer_finish 3 ,
 226 .Xr dwarf_producer_init 3 ,
 227 .Xr dwarf_producer_init_b 3 ,
 228 .Xr dwarf_transform_to_disk_form 3