1.\" $NetBSD: dwarf_get_relocation_info.3,v 1.4 2020/11/26 22:51:35 jkoshy 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 3644 2018-10-15 19:55:01Z 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.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 EXAMPLES 153To generate relocation entries and retrieve them, use: 154.Bd -literal -offset indent 155Dwarf_P_Debug dbg; 156Dwarf_Relocation_Data buf; 157Dwarf_Signed count, index, link; 158Dwarf_Unsigned reloc_cnt, entry_cnt; 159Dwarf_Error de; 160int version, i, j; 161 162/* 163 * Assume that dbg refers to a DWARF producer instance created 164 * created with DW_DLC_SYMBOLIC_RELOCATIONS flag set and that 165 * application code has added DWARF debugging information 166 * to the producer instance. 167 */ 168if ((count = dwarf_transform_to_disk_form(dbg, &de)) == 169 DW_DLV_NOCOUNT) { 170 warnx("dwarf_transform_to_disk_form failed: %s", 171 dwarf_errmsg(-1)); 172 return; 173} 174 175/* ... process generated section byte streams ... */ 176if (dwarf_get_relocation_info_count(dbg, &reloc_cnt, &version, &de) != 177 DW_DLV_OK) { 178 warnx("dwarf_get_relocation_info_count failed: %s", 179 dwarf_errmsg(-1)); 180 return; 181} 182 183for (i = 0; (Dwarf_Unsigned) i < reloc_cnt; i++) { 184 if (dwarf_get_relocation_info(dbg, &index, &link, &entry_cnt, 185 &buf, &de) != DW_DLV_OK) { 186 warnx("dwarf_get_relocation_info failed: %s", 187 dwarf_errmsg(-1)); 188 continue; 189 } 190 for (j = 0; (Dwarf_Unsigned) j < entry_cnt; j++) { 191 /* ...use each reloc data in buf[j]... */ 192 } 193} 194 195dwarf_producer_finish(dbg, &de); 196.Ed 197.Sh ERRORS 198Function 199.Fn dwarf_get_relocation_info 200can fail with: 201.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" 202.It Bq Er DW_DLE_ARGUMENT 203One of the arguments 204.Ar dbg , 205.Ar elf_section_index , 206.Ar elf_section_link , 207.Ar reloc_entry_count 208or 209.Ar reloc_buf 210was NULL. 211.It Bq Er DW_DLE_NO_ENTRY 212There were no more ELF relocation arrays to retrieve. 213.It Bq Er DW_DLE_NO_ENTRY 214The flag 215.Dv DW_DLC_SYMBOLIC_RELOCATIONS 216was not set on the producer instance. 217.It Bq Er DW_DLE_NO_ENTRY 218Function 219.Xr dwarf_transform_to_disk_form 3 220was not called prior to calling function 221.Fn dwarf_get_relocation_info . 222.El 223.Sh SEE ALSO 224.Xr dwarf 3 , 225.Xr dwarf_get_relocation_info_count 3 , 226.Xr dwarf_producer_finish 3 , 227.Xr dwarf_producer_init 3 , 228.Xr dwarf_producer_init_b 3 , 229.Xr dwarf_reset_section_bytes 3 , 230.Xr dwarf_transform_to_disk_form 3 231