1.\" $NetBSD: dwarf_add_AT_targ_address.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_AT_targ_address.3 2072 2011-10-27 03:26:49Z jkoshy 28.\" 29.Dd September 4, 2011 30.Os 31.Dt DWARF_ADD_AT_TARG_ADDRESS 3 32.Sh NAME 33.Nm dwarf_add_AT_targ_address , 34.Nm dwarf_add_AT_targ_address_b 35.Nd create and attach address class attributes 36.Sh LIBRARY 37.Lb libdwarf 38.Sh SYNOPSIS 39.In libdwarf.h 40.Ft Dwarf_P_Attribute 41.Fo dwarf_add_AT_targ_address 42.Fa "Dwarf_P_Debug dbg" 43.Fa "Dwarf_P_Die die" 44.Fa "Dwarf_Half attr" 45.Fa "Dwarf_Unsigned pc_value" 46.Fa "Dwarf_Signed sym_index" 47.Fa "Dwarf_Error *err" 48.Fc 49.Ft Dwarf_P_Attribute 50.Fo dwarf_add_AT_targ_address_b 51.Fa "Dwarf_P_Debug dbg" 52.Fa "Dwarf_P_Die die" 53.Fa "Dwarf_Half attr" 54.Fa "Dwarf_Unsigned pc_value" 55.Fa "Dwarf_Unsigned sym_index" 56.Fa "Dwarf_Error *err" 57.Fc 58.Sh DESCRIPTION 59Function 60.Fn dwarf_add_AT_targ_address_b 61creates an attribute descriptor belonging to the 62.Sq address 63class and attaches it to the debugging information entry referenced by 64argument 65.Ar die . 66.Pp 67The created attribute descriptor will have DWARF form 68.Dv DW_FORM_addr . 69If flag 70.Dv DW_DLC_SIZE_64 71is set on the producer instance, the attribute value will be 8 bytes 72in size. 73Otherwise the attribute value will be 4 bytes in size. 74.Pp 75Argument 76.Ar dbg 77should reference a DWARF producer instance allocated using 78.Xr dwarf_producer_init 3 79or 80.Xr dwarf_producer_init_b 3 . 81.Pp 82Argument 83.Ar die 84should reference a debugging information entry allocated using 85.Xr dwarf_new_die 3 . 86.Pp 87Argument 88.Ar attr 89should specify the attribute code of the created attribute descriptor. 90.Pp 91Argument 92.Ar pc_value 93should hold a relocatable address value which will become the value of 94the created attribute descriptor. 95.Pp 96Argument 97.Ar sym_index 98should specify the ELF symbol index of the symbol to be used for 99relocating the address value. 100.Pp 101If argument 102.Ar err 103is not NULL, it will be used to store error information in case 104of an error. 105.Pp 106Function 107.Fn dwarf_add_AT_targ_address 108is deprecated. 109It is similar to function 110.Fn dwarf_add_AT_targ_address_b 111except that it cannot handle all possible symbol index values. 112.Sh RETURN VALUES 113On success, these functions return the created attribute descriptor. 114In case of an error, these functions return 115.Dv DW_DLV_BADADDR 116and sets the argument 117.Ar err . 118.Sh ERRORS 119These functions can fail with: 120.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" 121.It Bq Er DW_DLE_ARGUMENT 122Either of the arguments 123.Ar dbg 124or 125.Ar die 126was NULL. 127.It Bq Er DW_DLE_MEMORY 128An out of memory condition was encountered during execution. 129.El 130.Sh SEE ALSO 131.Xr dwarf 3 , 132.Xr dwarf_add_AT_const_value_unsignedint 3 , 133.Xr dwarf_add_AT_dataref 3 , 134.Xr dwarf_add_AT_ref_address 3 , 135.Xr dwarf_add_AT_signed_const 3 , 136.Xr dwarf_add_AT_unsigned_const 3 , 137.Xr dwarf_new_die 3 , 138.Xr dwarf_producer_init 3 , 139.Xr dwarf_producer_init_b 3 140