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 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 EXAMPLES 151To generate relocation entries and retrieve them, use: 152.Bd -literal -offset indent 153Dwarf_P_Debug dbg; 154Dwarf_Relocation_Data buf; 155Dwarf_Signed count, index, link; 156Dwarf_Unsigned reloc_cnt, entry_cnt; 157Dwarf_Error de; 158int 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 */ 166if ((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 ... */ 174if (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 181for (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 193dwarf_producer_finish(dbg, &de); 194.Ed 195.Sh ERRORS 196Function 197.Fn dwarf_get_relocation_info 198can fail with: 199.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" 200.It Bq Er DW_DLE_ARGUMENT 201One of the arguments 202.Ar dbg , 203.Ar elf_section_index , 204.Ar elf_section_link , 205.Ar reloc_entry_count 206or 207.Ar reloc_buf 208was NULL. 209.It Bq Er DW_DLE_NO_ENTRY 210There were no more ELF relocation arrays to retrieve. 211.It Bq Er DW_DLE_NO_ENTRY 212The flag 213.Dv DW_DLC_SYMBOLIC_RELOCATIONS 214was not set on the producer instance. 215.It Bq Er DW_DLE_NO_ENTRY 216Function 217.Xr dwarf_transform_to_disk_form 3 218was 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 229