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 49The function 50.Fn dwarf_get_relocation_info 51is used to retrieve the relocation arrays generated by a prior call to 52.Xr dwarf_transform_to_disk_form 3 . 53.Pp 54Each call to this function retrieves the next available relocation 55array. 56Application code should call this function repeatly to retrieve all 57the relocation arrays. 58The total number of generated relocation arrays retrievable 59by this function may be obtained by calling function 60.Xr dwarf_get_relocation_info_count 3 . 61.Pp 62Argument 63.Ar dbg 64should reference a DWARF producer instance allocated using 65.Xr dwarf_producer_init 3 in sequence. 66or 67.Xr dwarf_producer_init_b 3 . 68The 69.Dv DW_DLC_SYMBOLIC_RELOCATIONS 70flag should have been set on the DWARF producer instance. 71.Pp 72Argument 73.Ar elf_section_index 74should point to a location which will be set to the ELF section index 75of the relocation section to which the retrieved relocation array 76belongs. 77.Pp 78Argument 79.Ar elf_section_link 80should point to a location which will be set to the section index of 81the ELF section to which the retrieved relocation array applies. 82.Pp 83Argument 84.Ar reloc_entry_count 85should point to a location which will be set to the total number of 86relocation entries contained in the relocation array. 87.Pp 88Argument 89.Ar reloc_buf 90should point to a location which will be set to a pointer to the 91retrieved array of relocation entries. 92.Pp 93If argument 94.Ar err 95is not NULL, it will be used to store error information in case 96of an error. 97.Pp 98The retrieved relocation entries are described using structure 99.Vt Dwarf_Relocation_Data_s , 100defined in the header file 101.In libdwarf.h : 102.Bd -literal -offset indent 103typedef 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 111Struct 112.Vt Dwarf_Relocation_Data_s 113consists of following fields: 114.Bl -tag -width ".Va drd_symbol_index" -compact -offset indent 115.It Va drd_type 116The type code of the relocation entry. 117The 118.Vt Dwarf_Rel_Type 119enumeration defined in the header file 120.In libdwarf.h 121specifies legal values for this field. 122.It Va drd_length 123The size in bytes of the field to be relocated. 124.It Va drd_offset 125The section-relative offset of the field to be relocated. 126.It Va drd_symbol_index 127The symbol index associated with the relocation entry. 128.El 129.Ss Memory Management 130The memory area used for the relocation arrays is managed by the 131.Lb libdwarf . 132The function 133.Fn dwarf_producer_finish 134may be used to release it, along with other resources associated 135with the producer instance. 136.Sh RETURN VALUES 137On success, function 138.Fn dwarf_get_relocation_info 139returns 140.Dv DW_DLV_OK . 141It returns 142.Dv DW_DLV_NO_ENTRY 143if there were no more relocation arrays to retrieve, or if the flag 144.Dv DW_DLC_SYMBOLIC_RELOCATIONS 145was not set on the producer instance. 146In case of an error, function 147.Fn dwarf_get_relocation_info 148returns 149.Dv DW_DLV_ERROR 150and sets the argument 151.Ar err . 152.Sh ERRORS 153Function 154.Fn dwarf_get_relocation_info 155can fail with: 156.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" 157.It Bq Er DW_DLE_ARGUMENT 158One of the arguments 159.Ar dbg , 160.Ar elf_section_index , 161.Ar elf_section_link , 162.Ar reloc_entry_count 163or 164.Ar reloc_buf 165was NULL. 166.It Bq Er DW_DLE_NO_ENTRY 167There were no more ELF relocation arrays to retrieve. 168.It Bq Er DW_DLE_NO_ENTRY 169The flag 170.Dv DW_DLC_SYMBOLIC_RELOCATIONS 171was not set on the producer instance. 172.It Bq Er DW_DLE_NO_ENTRY 173Function 174.Xr dwarf_transform_to_disk_form 3 175was not called prior to calling function 176.Fn dwarf_get_relocation_info . 177.El 178.Sh EXAMPLES 179To generate relocation entries and retrieve them, use: 180.Bd -literal -offset indent 181Dwarf_P_Debug dbg; 182Dwarf_Relocation_Data buf; 183Dwarf_Signed count, index, link; 184Dwarf_Unsigned reloc_cnt, entry_cnt; 185Dwarf_Error de; 186int 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 */ 194if ((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 ... */ 202if (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 209for (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 221dwarf_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 231