Annotation of src/external/bsd/elftoolchain/dist/libdwarf/dwarf_add_arange.3, Revision 1.2.8.2
1.2.8.2 ! tls 1: .\" $NetBSD$
! 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
! 59: Function
! 60: .Fn dwarf_add_arange_b
! 61: adds an address range entry to a producer instance.
! 62: .Pp
! 63: Argument
! 64: .Ar dbg
! 65: should reference a DWARF producer instance allocated using
! 66: .Xr dwarf_producer_init 3
! 67: or
! 68: .Xr dwarf_producer_init_b 3 .
! 69: .Pp
! 70: Argument
! 71: .Ar start
! 72: specifies the relocatable start address of the address range.
! 73: .Pp
! 74: Argument
! 75: .Ar length
! 76: specifies the length of the address range.
! 77: .Pp
! 78: Argument
! 79: .Ar symbol_index
! 80: specifies the ELF symbol index of the first symbol to be used for
! 81: relocation.
! 82: .Pp
! 83: Argument
! 84: .Ar end_symbol_index
! 85: specifies the ELF symbol index of the second symbol to be used for
! 86: relocation.
! 87: .Bl -bullet
! 88: .It
! 89: If argument
! 90: .Ar end_symbol_index
! 91: is not 0, the
! 92: .Dv DW_DLC_SYMBOLIC_RELOCATIONS
! 93: flag should have been set on the DWARF producer instance.
! 94: The address value specified by argument
! 95: .Ar start
! 96: will be treated as an offset value from the first symbol,
! 97: and the argument
! 98: .Ar offset_from_end_symbol
! 99: should hold an offset value from the second symbol.
! 100: Application code can retrieve the relocation entries for the
! 101: symbol pair by calling function
! 102: .Xr dwarf_get_relocation_info 3 .
! 103: The relocation entry for the first symbol will have type
! 104: .Dv dwarf_drt_first_of_length_pair
! 105: and the relocation entry for the second symbol will have type
! 106: .Dv dwarf_drt_second_of_length_pair .
! 107: .It
! 108: If argument
! 109: .Ar end_symbol_index
! 110: is 0, argument
! 111: .Ar offset_from_end_symbol
! 112: will be ignored and only one symbol is used for relocation.
! 113: .El
! 114: .Pp
! 115: If argument
! 116: .Ar err
! 117: is not NULL, it will be used to store error information in case
! 118: of an error.
! 119: .Pp
! 120: Function
! 121: .Fn dwarf_add_arange
! 122: is deprecated.
! 123: It is similar to function
! 124: .Fn dwarf_add_arange_b
! 125: except that it cannot handle all possible symbol index values
! 126: and supports only one relocation symbol.
! 127: .Sh RETURN VALUES
! 128: On success, these functions return a non-zero value.
! 129: In case of an error, these functions return 0 and set
! 130: the argument
! 131: .Ar err .
! 132: .Sh ERRORS
! 133: These functions can fail with:
! 134: .Bl -tag -width ".Bq Er DW_DLE_ARGUMENT"
! 135: .It Bq Er DW_DLE_ARGUMENT
! 136: Argument
! 137: .Ar dbg
! 138: was NULL.
! 139: .It Bq Er DW_DLE_ARGUMENT
! 140: Argument
! 141: .Ar end_symbol_index
! 142: was non-zero, but the flag
! 143: .Dv DW_DLC_SYMBOLIC_RELOCATIONS
! 144: was not set on the producer instance.
! 145: .It Bq Er DW_DLE_MEMORY
! 146: An out of memory condition was encountered during the execution of the
! 147: function.
! 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
CVSweb <webmaster@jp.NetBSD.org>