1.\" $NetBSD: dwarf_die_link.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_die_link.3 2073 2011-10-27 03:30:47Z jkoshy 28.\" 29.Dd September 4, 2011 30.Os 31.Dt DWARF_DIE_LINK 3 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.Ar die 55should specify the debugging information entry to be updated. 56.Pp 57Argument 58.Ar parent 59specifies the new parent link for the debugging information entry. 60.Pp 61Argument 62.Ar child 63specifies the new first child link for the debugging information entry. 64.Pp 65Argument 66.Ar left 67specifies the new left sibling link for the debugging information entry. 68.Pp 69Argument 70.Ar right 71specifies the new right sibling link for the debugging information entry. 72.Pp 73Only one of arguments 74.Ar parent , 75.Ar child , 76.Ar left 77and 78.Ar right 79is allowed to be non-NULL. 80Existing links to parent, child, left or right debugging information 81entries, if any, will be unlinked before the specified link is 82established. 83.Pp 84If argument 85.Ar err 86is not NULL, it will be used to store error information in case 87of an error. 88.Sh RETURN VALUES 89On success, function 90.Fn dwarf_die_link 91returns the debugging information entry provided in argument 92.Ar die . 93In case of an error, function 94.Fn dwarf_die_link 95returns 96.Dv DW_DLV_BADADDR 97and sets the argument 98.Ar err . 99.Sh ERRORS 100The function 101.Fn dwarf_die_link 102can fail with: 103.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" 104.It Bq Er DW_DLE_ARGUMENT 105Argument 106.Ar die 107was NULL. 108.It Bq Er DW_DLE_ARGUMENT 109More than one of the arguments 110.Ar parent , 111.Ar child , 112.Ar left 113and 114.Ar right 115were non-NULL. 116.El 117.Sh SEE ALSO 118.Xr dwarf 3 , 119.Xr dwarf_add_die_to_debug 3 , 120.Xr dwarf_new_die 3 121