external/bsd/elftoolchain/dist/libdwarf/dwarf_get_relocation_info.3

   1 .\"     $NetBSD: dwarf_get_relocation_info.3,v 1.2 2014/03/09 16:58:04 christos Exp $
   2 .\"
   3 .\" Copyright (c) 2011 Kai Wang
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .\" Id: dwarf_get_relocation_info.3 2071 2011-10-27 03:20:00Z jkoshy
  28 .\"
  29 .Dd September 3, 2011
  30 .Os
  31 .Dt DWARF_GET_RELOCATION_INFO 3
  32 .Sh NAME
  33 .Nm dwarf_get_relocation_info
  34 .Nd retrieve generated relocation arrays
  35 .Sh LIBRARY
  36 .Lb libdwarf
  37 .Sh SYNOPSIS
  38 .In libdwarf.h
  39 .Ft int
  40 .Fo dwarf_get_relocation_info
  41 .Fa "Dwarf_P_Debug dbg"
  42 .Fa "Dwarf_Signed *elf_section_index"
  43 .Fa "Dwarf_Signed *elf_section_link"
  44 .Fa "Dwarf_Unsigned *reloc_entry_count"
  45 .Fa "Dwarf_Relocation_Data *reloc_buf"
  46 .Fa "Dwarf_Error *err"
  47 .Fc
  48 .Sh DESCRIPTION
  49 The function
  50 .Fn dwarf_get_relocation_info
  51 is used to retrieve the relocation arrays generated by a prior call to
  52 .Xr dwarf_transform_to_disk_form 3 .
  53 .Pp
  54 Each call to this function retrieves the next available relocation
  55 array.
  56 Application code should call this function repeatly to retrieve all
  57 the relocation arrays.
  58 The total number of generated relocation arrays retrievable
  59 by this function may be obtained by calling function
  60 .Xr dwarf_get_relocation_info_count 3 .
  61 .Pp
  62 Argument
  63 .Ar dbg
  64 should reference a DWARF producer instance allocated using
  65 .Xr dwarf_producer_init 3 in sequence.
  66 or
  67 .Xr dwarf_producer_init_b 3 .
  68 The
  69 .Dv DW_DLC_SYMBOLIC_RELOCATIONS
  70 flag should have been set on the DWARF producer instance.
  71 .Pp
  72 Argument
  73 .Ar elf_section_index
  74 should point to a location which will be set to the ELF section index
  75 of the relocation section to which the retrieved relocation array
  76 belongs.
  77 .Pp
  78 Argument
  79 .Ar elf_section_link
  80 should point to a location which will be set to the section index of
  81 the ELF section to which the retrieved relocation array applies.
  82 .Pp
  83 Argument
  84 .Ar reloc_entry_count
  85 should point to a location which will be set to the total number of
  86 relocation entries contained in the relocation array.
  87 .Pp
  88 Argument
  89 .Ar reloc_buf
  90 should point to a location which will be set to a pointer to the
  91 retrieved array of relocation entries.
  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 .Pp
  98 The retrieved relocation entries are described using structure
  99 .Vt Dwarf_Relocation_Data_s ,
 100 defined in the header file
 101 .In libdwarf.h :
 102 .Bd -literal -offset indent
 103 typedef struct Dwarf_Relocation_Data_s {
 104         unsigned char drd_type;
 105         unsigned char drd_length;
 106         Dwarf_Unsigned drd_offset;
 107         Dwarf_Unsigned drd_symbol_index;
 108 } *Dwarf_Relocation_Data;
 109 .Ed
 110 .Pp
 111 Struct
 112 .Vt Dwarf_Relocation_Data_s
 113 consists of following fields:
 114 .Bl -tag -width ".Va drd_symbol_index" -compact -offset indent
 115 .It Va drd_type
 116 The type code of the relocation entry.
 117 The
 118 .Vt Dwarf_Rel_Type
 119 enumeration defined in the header file
 120 .In libdwarf.h
 121 specifies legal values for this field.
 122 .It Va drd_length
 123 The size in bytes of the field to be relocated.
 124 .It Va drd_offset
 125 The section-relative offset of the field to be relocated.
 126 .It Va drd_symbol_index
 127 The symbol index associated with the relocation entry.
 128 .El
 129 .Ss Memory Management
 130 The memory area used for the relocation arrays is managed by the
 131 .Lb libdwarf .
 132 The function
 133 .Fn dwarf_producer_finish
 134 may be used to release it, along with other resources associated
 135 with the producer instance.
 136 .Sh RETURN VALUES
 137 On success, function
 138 .Fn dwarf_get_relocation_info
 139 returns
 140 .Dv DW_DLV_OK .
 141 It returns
 142 .Dv DW_DLV_NO_ENTRY
 143 if there were no more relocation arrays to retrieve, or if the flag
 144 .Dv DW_DLC_SYMBOLIC_RELOCATIONS
 145 was not set on the producer instance.
 146 In case of an error, function
 147 .Fn dwarf_get_relocation_info
 148 returns
 149 .Dv DW_DLV_ERROR
 150 and sets the argument
 151 .Ar err .
 152 .Sh ERRORS
 153 Function
 154 .Fn dwarf_get_relocation_info
 155 can fail with:
 156 .Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY"
 157 .It Bq Er DW_DLE_ARGUMENT
 158 One of the arguments
 159 .Ar dbg ,
 160 .Ar elf_section_index ,
 161 .Ar elf_section_link ,
 162 .Ar reloc_entry_count
 163 or
 164 .Ar reloc_buf
 165 was NULL.
 166 .It Bq Er DW_DLE_NO_ENTRY
 167 There were no more ELF relocation arrays to retrieve.
 168 .It Bq Er DW_DLE_NO_ENTRY
 169 The flag
 170 .Dv DW_DLC_SYMBOLIC_RELOCATIONS
 171 was not set on the producer instance.
 172 .It Bq Er DW_DLE_NO_ENTRY
 173 Function
 174 .Xr dwarf_transform_to_disk_form 3
 175 was not called prior to calling function
 176 .Fn dwarf_get_relocation_info .
 177 .El
 178 .Sh EXAMPLES
 179 To generate relocation entries and retrieve them, use:
 180 .Bd -literal -offset indent
 181 Dwarf_P_Debug dbg;
 182 Dwarf_Relocation_Data buf;
 183 Dwarf_Signed count, index, link;
 184 Dwarf_Unsigned reloc_cnt, entry_cnt;
 185 Dwarf_Error de;
 186 int version, i, j;
 187
 188 /*
 189  * Assume that dbg refers to a DWARF producer instance created
 190  * created with DW_DLC_SYMBOLIC_RELOCATIONS flag set and that
 191  * application code has added DWARF debugging information
 192  * to the producer instance.
 193  */
 194 if ((count = dwarf_transform_to_disk_form(dbg, &de)) ==
 195     DW_DLV_NOCOUNT) {
 196         warnx("dwarf_transform_to_disk_form failed: %s",
 197             dwarf_errmsg(-1));
 198         return;
 199 }
 200
 201 /* ... process generated section byte streams ... */
 202 if (dwarf_get_relocation_info_count(dbg, &reloc_cnt, &version, &de) !=
 203     DW_DLV_OK) {
 204         warnx("dwarf_get_relocation_info_count failed: %s",
 205             dwarf_errmsg(-1));
 206         return;
 207 }
 208
 209 for (i = 0; (Dwarf_Unsigned) i < reloc_cnt; i++) {
 210         if (dwarf_get_relocation_info(dbg, &index, &link, &entry_cnt,
 211             &buf, &de) != DW_DLV_OK) {
 212                 warnx("dwarf_get_relocation_info failed: %s",
 213                     dwarf_errmsg(-1));
 214                 continue;
 215         }
 216         for (j = 0; (Dwarf_Unsigned) j < entry_cnt; j++) {
 217                 /* ...use each reloc data in buf[j]... */
 218         }
 219 }
 220
 221 dwarf_producer_finish(dbg, &de);
 222 .Ed
 223 .Sh SEE ALSO
 224 .Xr dwarf 3 ,
 225 .Xr dwarf_get_relocation_info_count 3 ,
 226 .Xr dwarf_reset_section_bytes 3 ,
 227 .Xr dwarf_producer_finish 3 ,
 228 .Xr dwarf_producer_init 3 ,
 229 .Xr dwarf_producer_init_b 3 ,
 230 .Xr dwarf_transform_to_disk_form 3