1.\" $NetBSD: dwarf_add_AT_targ_address.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_AT_targ_address.3 3961 2022-03-12 15:13:22Z jkoshy 28.\" 29.Dd September 4, 2011 30.Dt DWARF_ADD_AT_TARG_ADDRESS 3 31.Os 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.Fa 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.Fa 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.Fa die 84should reference a debugging information entry allocated using 85.Xr dwarf_new_die 3 . 86.Pp 87Argument 88.Fa attr 89should specify the attribute code of the created attribute descriptor. 90.Pp 91Argument 92.Fa pc_value 93should hold a relocatable address value which will become the value of 94the created attribute descriptor. 95.Pp 96Argument 97.Fa sym_index 98should specify the ELF symbol index of the symbol to be used for 99relocating the address value. 100.Pp 101If argument 102.Fa err 103is not 104.Dv NULL , 105it will be used to store error information in case of an error. 106.Pp 107Function 108.Fn dwarf_add_AT_targ_address 109is deprecated. 110It is similar to function 111.Fn dwarf_add_AT_targ_address_b 112except that it cannot handle all possible symbol index values. 113.Sh RETURN VALUES 114On success, these functions return the created attribute descriptor. 115In case of an error, these functions return 116.Dv DW_DLV_BADADDR 117and sets the argument 118.Fa err . 119.Sh ERRORS 120These functions can fail with: 121.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" 122.It Bq Er DW_DLE_ARGUMENT 123Either of the arguments 124.Fa dbg 125or 126.Fa die 127was 128.Dv NULL . 129.It Bq Er DW_DLE_MEMORY 130An out of memory condition was encountered during execution. 131.El 132.Sh SEE ALSO 133.Xr dwarf 3 , 134.Xr dwarf_add_AT_const_value_unsignedint 3 , 135.Xr dwarf_add_AT_dataref 3 , 136.Xr dwarf_add_AT_ref_address 3 , 137.Xr dwarf_add_AT_signed_const 3 , 138.Xr dwarf_add_AT_unsigned_const 3 , 139.Xr dwarf_new_die 3 , 140.Xr dwarf_producer_init 3 , 141.Xr dwarf_producer_init_b 3 142