1.\" $NetBSD: dwarf_get_relocation_info.3,v 1.6 2024/03/03 17:37:31 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 3963 2022-03-12 16:07:32Z jkoshy 28.\" 29.Dd September 3, 2011 30.Dt DWARF_GET_RELOCATION_INFO 3 31.Os 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.Fa 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.Fa 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.Fa 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.Fa 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.Fa 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.Fa err 95is not 96.Dv NULL , 97it will be used to store error information in case of an error. 98.Pp 99The retrieved relocation entries are described using structure 100.Vt Dwarf_Relocation_Data_s , 101defined in the header file 102.In libdwarf.h : 103.Bd -literal -offset indent 104typedef struct Dwarf_Relocation_Data_s { 105 unsigned char drd_type; 106 unsigned char drd_length; 107 Dwarf_Unsigned drd_offset; 108 Dwarf_Unsigned drd_symbol_index; 109} *Dwarf_Relocation_Data; 110.Ed 111.Pp 112Struct 113.Vt Dwarf_Relocation_Data_s 114consists of following fields: 115.Bl -tag -width ".Va drd_symbol_index" -compact -offset indent 116.It Va drd_type 117The type code of the relocation entry. 118The 119.Vt Dwarf_Rel_Type 120enumeration defined in the header file 121.In libdwarf.h 122specifies legal values for this field. 123.It Va drd_length 124The size in bytes of the field to be relocated. 125.It Va drd_offset 126The section-relative offset of the field to be relocated. 127.It Va drd_symbol_index 128The symbol index associated with the relocation entry. 129.El 130.Ss Memory Management 131The memory area used for the relocation arrays is managed by the 132.Lb libdwarf . 133The function 134.Fn dwarf_producer_finish 135may be used to release it, along with other resources associated 136with the producer instance. 137.Sh RETURN VALUES 138On success, function 139.Fn dwarf_get_relocation_info 140returns 141.Dv DW_DLV_OK . 142It returns 143.Dv DW_DLV_NO_ENTRY 144if there were no more relocation arrays to retrieve, or if the flag 145.Dv DW_DLC_SYMBOLIC_RELOCATIONS 146was not set on the producer instance. 147In case of an error, function 148.Fn dwarf_get_relocation_info 149returns 150.Dv DW_DLV_ERROR 151and sets the argument 152.Fa err . 153.Sh EXAMPLES 154To generate relocation entries and retrieve them, use: 155.Bd -literal -offset indent 156Dwarf_P_Debug dbg; 157Dwarf_Relocation_Data buf; 158Dwarf_Signed count, index, link; 159Dwarf_Unsigned reloc_cnt, entry_cnt; 160Dwarf_Error de; 161int version, i, j; 162 163/* 164 * Assume that dbg refers to a DWARF producer instance created 165 * created with DW_DLC_SYMBOLIC_RELOCATIONS flag set and that 166 * application code has added DWARF debugging information 167 * to the producer instance. 168 */ 169if ((count = dwarf_transform_to_disk_form(dbg, &de)) == 170 DW_DLV_NOCOUNT) { 171 warnx("dwarf_transform_to_disk_form failed: %s", 172 dwarf_errmsg(-1)); 173 return; 174} 175 176/* ... process generated section byte streams ... */ 177if (dwarf_get_relocation_info_count(dbg, &reloc_cnt, &version, &de) != 178 DW_DLV_OK) { 179 warnx("dwarf_get_relocation_info_count failed: %s", 180 dwarf_errmsg(-1)); 181 return; 182} 183 184for (i = 0; (Dwarf_Unsigned) i < reloc_cnt; i++) { 185 if (dwarf_get_relocation_info(dbg, &index, &link, &entry_cnt, 186 &buf, &de) != DW_DLV_OK) { 187 warnx("dwarf_get_relocation_info failed: %s", 188 dwarf_errmsg(-1)); 189 continue; 190 } 191 for (j = 0; (Dwarf_Unsigned) j < entry_cnt; j++) { 192 /* ...use each reloc data in buf[j]... */ 193 } 194} 195 196dwarf_producer_finish(dbg, &de); 197.Ed 198.Sh ERRORS 199Function 200.Fn dwarf_get_relocation_info 201can fail with: 202.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" 203.It Bq Er DW_DLE_ARGUMENT 204One of the arguments 205.Fa dbg , 206.Fa elf_section_index , 207.Fa elf_section_link , 208.Fa reloc_entry_count 209or 210.Fa reloc_buf 211was 212.Dv NULL . 213.It Bq Er DW_DLE_NO_ENTRY 214There were no more ELF relocation arrays to retrieve. 215.It Bq Er DW_DLE_NO_ENTRY 216The flag 217.Dv DW_DLC_SYMBOLIC_RELOCATIONS 218was not set on the producer instance. 219.It Bq Er DW_DLE_NO_ENTRY 220Function 221.Xr dwarf_transform_to_disk_form 3 222was not called prior to calling function 223.Fn dwarf_get_relocation_info . 224.El 225.Sh SEE ALSO 226.Xr dwarf 3 , 227.Xr dwarf_get_relocation_info_count 3 , 228.Xr dwarf_producer_finish 3 , 229.Xr dwarf_producer_init 3 , 230.Xr dwarf_producer_init_b 3 , 231.Xr dwarf_reset_section_bytes 3 , 232.Xr dwarf_transform_to_disk_form 3 233