1.\" $NetBSD: dwarf_die_link.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_die_link.3 3962 2022-03-12 15:56:10Z jkoshy 28.\" 29.Dd September 4, 2011 30.Dt DWARF_DIE_LINK 3 31.Os 32.Sh NAME 33.Nm dwarf_die_link 34.Nd link a debugging information entry 35.Sh LIBRARY 36.Lb libdwarf 37.Sh SYNOPSIS 38.In libdwarf.h 39.Ft Dwarf_P_Die 40.Fo dwarf_die_link 41.Fa "Dwarf_P_Die die" 42.Fa "Dwarf_P_Die parent" 43.Fa "Dwarf_P_Die child" 44.Fa "Dwarf_P_Die left" 45.Fa "Dwarf_P_Die right" 46.Fa "Dwarf_Error *err" 47.Fc 48.Sh DESCRIPTION 49Function 50.Fn dwarf_die_link 51links debugging information entries together. 52.Pp 53Argument 54.Fa die 55should specify the debugging information entry to be updated. 56.Pp 57Argument 58.Fa parent 59specifies the new parent link for the debugging information entry. 60.Pp 61Argument 62.Fa child 63specifies the new first child link for the debugging information entry. 64.Pp 65Argument 66.Fa left 67specifies the new left sibling link for the debugging information entry. 68.Pp 69Argument 70.Fa right 71specifies the new right sibling link for the debugging information entry. 72.Pp 73Only one of arguments 74.Fa parent , 75.Fa child , 76.Fa left 77and 78.Fa right 79is allowed to be 80.No non- Ns Dv NULL . 81Existing links to parent, child, left or right debugging information 82entries, if any, will be unlinked before the specified link is 83established. 84.Pp 85If argument 86.Fa err 87is not 88.Dv NULL , 89it will be used to store error information in case of an error. 90.Sh RETURN VALUES 91On success, function 92.Fn dwarf_die_link 93returns the debugging information entry provided in argument 94.Fa die . 95In case of an error, function 96.Fn dwarf_die_link 97returns 98.Dv DW_DLV_BADADDR 99and sets the argument 100.Fa err . 101.Sh ERRORS 102The function 103.Fn dwarf_die_link 104can fail with: 105.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" 106.It Bq Er DW_DLE_ARGUMENT 107Argument 108.Fa die 109was 110.Dv NULL . 111.It Bq Er DW_DLE_ARGUMENT 112More than one of the arguments 113.Fa parent , 114.Fa child , 115.Fa left 116and 117.Fa right 118were 119.No non- Ns Dv NULL . 120.El 121.Sh SEE ALSO 122.Xr dwarf 3 , 123.Xr dwarf_add_die_to_debug 3 , 124.Xr dwarf_new_die 3 125