1.\" $NetBSD: dwarf_new_die.3,v 1.6 2024/03/03 17:37:31 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_new_die.3 3963 2022-03-12 16:07:32Z jkoshy 28.\" 29.Dd September 4, 2011 30.Dt DWARF_NEW_DIE 3 31.Os 32.Sh NAME 33.Nm dwarf_new_die 34.Nd allocate a new debugging information entry 35.Sh LIBRARY 36.Lb libdwarf 37.Sh SYNOPSIS 38.In libdwarf.h 39.Ft Dwarf_P_Die 40.Fo dwarf_new_die 41.Fa "Dwarf_P_Debug dbg" 42.Fa "Dwarf_Tag tag" 43.Fa "Dwarf_P_Die parent" 44.Fa "Dwarf_P_Die child" 45.Fa "Dwarf_P_Die left" 46.Fa "Dwarf_P_Die right" 47.Fa "Dwarf_Error *err" 48.Fc 49.Sh DESCRIPTION 50Function 51.Fn dwarf_new_die 52allocates a new DWARF debugging information entry and links it 53to another debugging information entry. 54.Pp 55Argument 56.Fa dbg 57should reference a DWARF producer instance allocated using 58.Xr dwarf_producer_init 3 59or 60.Xr dwarf_producer_init_b 3 . 61.Pp 62Argument 63.Fa tag 64should specify the tag of the newly created debugging information entry. 65Valid values for this argument are those for the 66.Dv DW_TAG_ Ns * 67symbols defined in 68.In libdwarf.h . 69.Pp 70Argument 71.Fa parent 72specifies the parent link of the debugging information entry. 73.Pp 74Argument 75.Fa child 76specifies the first child link of the debugging information entry. 77.Pp 78Argument 79.Fa left 80specifies the left sibling link of the debugging information entry. 81.Pp 82Argument 83.Fa right 84specifies the right sibling link of the debugging information entry. 85.Pp 86Only one of arguments 87.Fa parent , 88.Fa child , 89.Fa left 90and 91.Fa right 92is allowed to be 93.No non- Ns Dv NULL . 94Application code can subsequently call the function 95.Xr dwarf_die_link 3 96to change the links for the created debugging information entry. 97.Pp 98If argument 99.Fa err 100is not 101.Dv NULL , 102it will be used to store error information in case of an error. 103.Sh RETURN VALUES 104On success, function 105.Fn dwarf_new_die 106returns the newly created debugging information entry. 107In case of an error, function 108.Fn dwarf_new_die 109returns 110.Dv DW_DLV_BADADDR 111and sets the argument 112.Fa err . 113.Sh EXAMPLES 114To create debugging information entries and add them to the producer 115instance, use: 116.Bd -literal -offset indent 117Dwarf_P_Debug dbg; 118Dwarf_P_Die die1, die2; 119Dwarf_Error de; 120 121/* ... assume dbg refers to a DWARF producer instance ... */ 122 123die1 = dwarf_new_die(dbg, DW_TAG_compilation_unit, NULL, NULL, NULL, 124 NULL, &de); 125if (die1 == NULL) { 126 warnx("dwarf_new_die failed: %s", dwarf_errmsg(-1)); 127 return; 128} 129 130die2 = dwarf_new_die(dbg, DW_TAG_base_type, die1, NULL, NULL, 131 NULL, &de); 132if (die1 == NULL) { 133 warnx("dwarf_new_die failed: %s", dwarf_errmsg(-1)); 134 return; 135} 136 137if (dwarf_add_die_to_debug(dbg, die1, &de) != DW_DLV_OK) { 138 warnx("dwarf_add_die_to_debug failed: %s", dwarf_errmsg(-1)); 139 return; 140} 141.Ed 142.Sh ERRORS 143Function 144.Fn dwarf_new_die 145can fail with: 146.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" 147.It Bq Er DW_DLE_ARGUMENT 148Argument 149.Fa dbg 150was 151.Dv NULL . 152.It Bq Er DW_DLE_ARGUMENT 153More than one of the arguments 154.Fa parent , 155.Fa child , 156.Fa left 157and 158.Fa right 159were 160.No non- Ns Dv NULL . 161.It Bq Er DW_DLE_MEMORY 162An out of memory condition was encountered during the execution of the 163function. 164.El 165.Sh SEE ALSO 166.Xr dwarf 3 , 167.Xr dwarf_add_die_to_debug 3 , 168.Xr dwarf_die_link 3 , 169.Xr dwarf_producer_init 3 , 170.Xr dwarf_producer_init_b 3 171