1.\" $NetBSD: dwarf_add_arange.3,v 1.2 2014/03/09 16:58:03 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 2072 2011-10-27 03:26:49Z jkoshy 28.\" 29.Dd September 18, 2011 30.Os 31.Dt DWARF_ADD_ARANGE 3 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.Ar 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.Ar start 72specifies the relocatable start address of the address range. 73.Pp 74Argument 75.Ar length 76specifies the length of the address range. 77.Pp 78Argument 79.Ar symbol_index 80specifies the ELF symbol index of the first symbol to be used for 81relocation. 82.Pp 83Argument 84.Ar 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.Ar 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.Ar start 96will be treated as an offset value from the first symbol, 97and the argument 98.Ar 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.Ar end_symbol_index 110is 0, argument 111.Ar offset_from_end_symbol 112will be ignored and only one symbol is used for relocation. 113.El 114.Pp 115If argument 116.Ar err 117is not NULL, it will be used to store error information in case 118of an error. 119.Pp 120Function 121.Fn dwarf_add_arange 122is deprecated. 123It is similar to function 124.Fn dwarf_add_arange_b 125except that it cannot handle all possible symbol index values 126and supports only one relocation symbol. 127.Sh RETURN VALUES 128On success, these functions return a non-zero value. 129In case of an error, these functions return 0 and set 130the argument 131.Ar err . 132.Sh ERRORS 133These functions can fail with: 134.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" 135.It Bq Er DW_DLE_ARGUMENT 136Argument 137.Ar dbg 138was NULL. 139.It Bq Er DW_DLE_ARGUMENT 140Argument 141.Ar end_symbol_index 142was non-zero, but the flag 143.Dv DW_DLC_SYMBOLIC_RELOCATIONS 144was not set on the producer instance. 145.It Bq Er DW_DLE_MEMORY 146An out of memory condition was encountered during the execution of the 147function. 148.El 149.Sh SEE ALSO 150.Xr dwarf 3 , 151.Xr dwarf_get_relocation_info 3 , 152.Xr dwarf_producer_init 3 , 153.Xr dwarf_producer_init_b 3 154