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