1.\" $NetBSD: dwarf_add_arange.3,v 1.6 2024/03/03 17:37:30 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_add_arange.3 3961 2022-03-12 15:13:22Z jkoshy 28.\" 29.Dd September 18, 2011 30.Dt DWARF_ADD_ARANGE 3 31.Os 32.Sh NAME 33.Nm dwarf_add_arange , 34.Nm dwarf_add_arange_b 35.Nd add address range information to a DWARF producer instance 36.Sh LIBRARY 37.Lb libdwarf 38.Sh SYNOPSIS 39.In libdwarf.h 40.Ft "Dwarf_Unsigned" 41.Fo dwarf_add_arange 42.Fa "Dwarf_P_Debug dbg" 43.Fa "Dwarf_Addr start" 44.Fa "Dwarf_Unsigned length" 45.Fa "Dwarf_Signed symbol_index" 46.Fa "Dwarf_Error *err" 47.Fc 48.Ft "Dwarf_Unsigned" 49.Fo dwarf_add_arange_b 50.Fa "Dwarf_P_Debug dbg" 51.Fa "Dwarf_Addr start" 52.Fa "Dwarf_Unsigned length" 53.Fa "Dwarf_Unsigned symbol_index" 54.Fa "Dwarf_Unsigned end_symbol_index" 55.Fa "Dwarf_Addr offset_from_end_symbol" 56.Fa "Dwarf_Error *err" 57.Fc 58.Sh DESCRIPTION 59Function 60.Fn dwarf_add_arange_b 61adds an address range entry to a producer instance. 62.Pp 63Argument 64.Fa dbg 65should reference a DWARF producer instance allocated using 66.Xr dwarf_producer_init 3 67or 68.Xr dwarf_producer_init_b 3 . 69.Pp 70Argument 71.Fa start 72specifies the relocatable start address of the address range. 73.Pp 74Argument 75.Fa length 76specifies the length of the address range. 77.Pp 78Argument 79.Fa symbol_index 80specifies the ELF symbol index of the first symbol to be used for 81relocation. 82.Pp 83Argument 84.Fa end_symbol_index 85specifies the ELF symbol index of the second symbol to be used for 86relocation. 87.Bl -bullet 88.It 89If argument 90.Fa end_symbol_index 91is not 0, the 92.Dv DW_DLC_SYMBOLIC_RELOCATIONS 93flag should have been set on the DWARF producer instance. 94The address value specified by argument 95.Fa start 96will be treated as an offset value from the first symbol, 97and the argument 98.Fa offset_from_end_symbol 99should hold an offset value from the second symbol. 100Application code can retrieve the relocation entries for the 101symbol pair by calling function 102.Xr dwarf_get_relocation_info 3 . 103The relocation entry for the first symbol will have type 104.Dv dwarf_drt_first_of_length_pair 105and the relocation entry for the second symbol will have type 106.Dv dwarf_drt_second_of_length_pair . 107.It 108If argument 109.Fa end_symbol_index 110is 0, argument 111.Fa offset_from_end_symbol 112will be ignored and only one symbol is used for relocation. 113.El 114.Pp 115If argument 116.Fa err 117is not 118.Dv NULL , 119it will be used to store error information in case of an error. 120.Pp 121Function 122.Fn dwarf_add_arange 123is deprecated. 124It is similar to function 125.Fn dwarf_add_arange_b 126except that it cannot handle all possible symbol index values 127and supports only one relocation symbol. 128.Sh RETURN VALUES 129On success, these functions return a non-zero value. 130In case of an error, these functions return 0 and set 131the argument 132.Fa err . 133.Sh ERRORS 134These functions can fail with: 135.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" 136.It Bq Er DW_DLE_ARGUMENT 137Argument 138.Fa dbg 139was 140.Dv NULL . 141.It Bq Er DW_DLE_ARGUMENT 142Argument 143.Fa end_symbol_index 144was non-zero, but the flag 145.Dv DW_DLC_SYMBOLIC_RELOCATIONS 146was not set on the producer instance. 147.It Bq Er DW_DLE_MEMORY 148An out of memory condition was encountered during the execution of the 149function. 150.El 151.Sh SEE ALSO 152.Xr dwarf 3 , 153.Xr dwarf_get_relocation_info 3 , 154.Xr dwarf_producer_init 3 , 155.Xr dwarf_producer_init_b 3 156