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