1*5ac3bc71Schristos.\" $NetBSD: dwarf_add_AT_reference.3,v 1.6 2024/03/03 17:37:30 christos Exp $ 2e81373b4Schristos.\" 39dd9d0cfSchristos.\" Copyright (c) 2011 Kai Wang 49dd9d0cfSchristos.\" All rights reserved. 59dd9d0cfSchristos.\" 69dd9d0cfSchristos.\" Redistribution and use in source and binary forms, with or without 79dd9d0cfSchristos.\" modification, are permitted provided that the following conditions 89dd9d0cfSchristos.\" are met: 99dd9d0cfSchristos.\" 1. Redistributions of source code must retain the above copyright 109dd9d0cfSchristos.\" notice, this list of conditions and the following disclaimer. 119dd9d0cfSchristos.\" 2. Redistributions in binary form must reproduce the above copyright 129dd9d0cfSchristos.\" notice, this list of conditions and the following disclaimer in the 139dd9d0cfSchristos.\" documentation and/or other materials provided with the distribution. 149dd9d0cfSchristos.\" 159dd9d0cfSchristos.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 169dd9d0cfSchristos.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 179dd9d0cfSchristos.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 189dd9d0cfSchristos.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 199dd9d0cfSchristos.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 209dd9d0cfSchristos.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 219dd9d0cfSchristos.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 229dd9d0cfSchristos.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 239dd9d0cfSchristos.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 249dd9d0cfSchristos.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 259dd9d0cfSchristos.\" SUCH DAMAGE. 269dd9d0cfSchristos.\" 27cdbf1fe1Sjkoshy.\" Id: dwarf_add_AT_reference.3 3961 2022-03-12 15:13:22Z jkoshy 289dd9d0cfSchristos.\" 299dd9d0cfSchristos.Dd September 4, 2011 309dd9d0cfSchristos.Dt DWARF_ADD_AT_REFERENCE 3 31604b0842Sjkoshy.Os 329dd9d0cfSchristos.Sh NAME 339dd9d0cfSchristos.Nm dwarf_add_AT_reference 349dd9d0cfSchristos.Nd create and attach an attribute that references another DIE 359dd9d0cfSchristos.Sh LIBRARY 369dd9d0cfSchristos.Lb libdwarf 379dd9d0cfSchristos.Sh SYNOPSIS 389dd9d0cfSchristos.In libdwarf.h 399dd9d0cfSchristos.Ft "Dwarf_P_Attribute" 409dd9d0cfSchristos.Fo dwarf_add_AT_reference 419dd9d0cfSchristos.Fa "Dwarf_P_Debug dbg" 429dd9d0cfSchristos.Fa "Dwarf_P_Die die" 439dd9d0cfSchristos.Fa "Dwarf_Half attr" 449dd9d0cfSchristos.Fa "Dwarf_P_Die ref_die" 459dd9d0cfSchristos.Fa "Dwarf_Error *err" 469dd9d0cfSchristos.Fc 479dd9d0cfSchristos.Sh DESCRIPTION 489dd9d0cfSchristosFunction 499dd9d0cfSchristos.Fn dwarf_add_AT_reference 509dd9d0cfSchristoscreates an attribute descriptor that references another debugging 519dd9d0cfSchristosinformation entry in the same compilation unit. 529dd9d0cfSchristosThe attribute will be of DWARF form 539dd9d0cfSchristos.Dv DW_FORM_ref4 549dd9d0cfSchristosor 559dd9d0cfSchristos.Dv DW_FORM_ref8 569dd9d0cfSchristosdepending on the target address size, and will contain the 579dd9d0cfSchristossection-relative offset of the referenced debugging information entry 589dd9d0cfSchristosas its value. 599dd9d0cfSchristos.Pp 609dd9d0cfSchristosArgument 61cdbf1fe1Sjkoshy.Fa dbg 629dd9d0cfSchristosshould reference a DWARF producer instance allocated using 639dd9d0cfSchristos.Xr dwarf_producer_init 3 649dd9d0cfSchristosor 659dd9d0cfSchristos.Xr dwarf_producer_init_b 3 . 669dd9d0cfSchristos.Pp 679dd9d0cfSchristosArgument 68cdbf1fe1Sjkoshy.Fa die 699dd9d0cfSchristosshould reference a debugging information entry allocated using 709dd9d0cfSchristos.Xr dwarf_new_die 3 . 719dd9d0cfSchristos.Pp 729dd9d0cfSchristosArgument 73cdbf1fe1Sjkoshy.Fa attr 749dd9d0cfSchristosshould specify the attribute code of the created attribute descriptor. 759dd9d0cfSchristos.Pp 769dd9d0cfSchristosArgument 77cdbf1fe1Sjkoshy.Fa ref_die 789dd9d0cfSchristosshould hold the debugging information entry descriptor that 799dd9d0cfSchristosthe attribute should refer to. 809dd9d0cfSchristos.Pp 819dd9d0cfSchristosIf argument 82cdbf1fe1Sjkoshy.Fa err 83cdbf1fe1Sjkoshyis not 84cdbf1fe1Sjkoshy.Dv NULL , 85cdbf1fe1Sjkoshyit will be used to store error information in case of an error. 869dd9d0cfSchristos.Sh RETURN VALUES 879dd9d0cfSchristosOn success, function 889dd9d0cfSchristos.Fn dwarf_add_AT_reference 899dd9d0cfSchristosreturns the created attribute descriptor. 909dd9d0cfSchristosIn case of an error, function 919dd9d0cfSchristos.Fn dwarf_add_AT_reference 929dd9d0cfSchristosreturns 939dd9d0cfSchristos.Dv DW_DLV_BADADDR 949dd9d0cfSchristosand sets the argument 95cdbf1fe1Sjkoshy.Fa err . 969dd9d0cfSchristos.Sh ERRORS 979dd9d0cfSchristosFunction 989dd9d0cfSchristos.Fn dwarf_add_AT_reference 999dd9d0cfSchristoscan fail with: 1009dd9d0cfSchristos.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" 1019dd9d0cfSchristos.It Bq Er DW_DLE_ARGUMENT 1029dd9d0cfSchristosOne of the arguments 103cdbf1fe1Sjkoshy.Fa dbg , 104cdbf1fe1Sjkoshy.Fa die 1059dd9d0cfSchristosor 106cdbf1fe1Sjkoshy.Fa ref_die 107cdbf1fe1Sjkoshywas 108cdbf1fe1Sjkoshy.Dv NULL . 1099dd9d0cfSchristos.It Bq Er DW_DLE_MEMORY 1109dd9d0cfSchristosAn out of memory condition was encountered during the execution of 1119dd9d0cfSchristosthe function. 1129dd9d0cfSchristos.El 1139dd9d0cfSchristos.Sh SEE ALSO 1149dd9d0cfSchristos.Xr dwarf 3 , 1159dd9d0cfSchristos.Xr dwarf_add_AT_dataref 3 , 1169dd9d0cfSchristos.Xr dwarf_add_AT_ref_address 3 , 1179dd9d0cfSchristos.Xr dwarf_add_AT_signed_const 3 , 1189dd9d0cfSchristos.Xr dwarf_add_AT_unsigned_const 3 , 1199dd9d0cfSchristos.Xr dwarf_new_die 3 , 1209dd9d0cfSchristos.Xr dwarf_producer_init 3 , 1219dd9d0cfSchristos.Xr dwarf_producer_init_b 3 122