1.\" $NetBSD: dwarf_dieoffset.3,v 1.6 2024/03/03 17:37:30 christos Exp $ 2.\" 3.\" Copyright (c) 2010,2014 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_dieoffset.3 3962 2022-03-12 15:56:10Z jkoshy 28.\" 29.Dd December 21, 2014 30.Dt DWARF_DIEOFFSET 3 31.Os 32.Sh NAME 33.Nm dwarf_die_CU_offset , 34.Nm dwarf_die_CU_offset_range , 35.Nm dwarf_dieoffset , 36.Nm dwarf_get_cu_die_offset_given_cu_header_offset , 37.Nm dwarf_get_cu_die_offset_given_cu_header_offset_b 38.Nd return offsets of DWARF debugging information entries 39.Sh LIBRARY 40.Lb libdwarf 41.Sh SYNOPSIS 42.In libdwarf.h 43.Ft int 44.Fo dwarf_die_CU_offset 45.Fa "Dwarf_Die die" 46.Fa "Dwarf_Off *ret_offset" 47.Fa "Dwarf_Error *err" 48.Fc 49.Ft int 50.Fo dwarf_die_CU_offset_range 51.Fa "Dwarf_Die die" 52.Fa "Dwarf_Off *cu_offset" 53.Fa "Dwarf_Off *cu_length" 54.Fa "Dwarf_Error *err" 55.Fc 56.Ft int 57.Fo dwarf_dieoffset 58.Fa "Dwarf_Die die" 59.Fa "Dwarf_Off *ret_offset" 60.Fa "Dwarf_Error *err" 61.Fc 62.Ft int 63.Fo dwarf_get_cu_die_offset_given_cu_header_offset 64.Fa "Dwarf_Debug dbg" 65.Fa "Dwarf_Off in_cu_header_offset" 66.Fa "Dwarf_Off *out_cu_die_offset" 67.Fa "Dwarf_Error *err" 68.Fc 69.Ft int 70.Fo dwarf_get_cu_die_offset_given_cu_header_offset_b 71.Fa "Dwarf_Debug dbg" 72.Fa "Dwarf_Off in_cu_header_offset" 73.Fa "Dwarf_Bool is_info" 74.Fa "Dwarf_Off *out_cu_die_offset" 75.Fa "Dwarf_Error *err" 76.Fc 77.Sh DESCRIPTION 78These functions are used to retrieve offsets for DWARF debugging 79information entries. 80.Pp 81Function 82.Fn dwarf_die_CU_offset 83returns the offset of the debugging information entry referenced by 84argument 85.Fa die 86relative to the start of its containing compilation unit. 87Argument 88.Fa ret_offset 89should point to the location that is to hold the returned offset. 90If argument 91.Fa err 92is 93.No non- Ns Dv NULL , 94it will be used to return an error descriptor in case of an error. 95.Pp 96Function 97.Fn dwarf_die_CU_offset_range 98returns the section-relative offset and length of the compilation unit 99containing the debugging information entry referenced by argument 100.Fa die . 101Argument 102.Fa cu_offset 103should point to a location that will hold the returned offset. 104Argument 105.Fa cu_length 106should point to a location that will hold the returned length of the 107compilation unit. 108If argument 109.Fa err 110is 111.No non- Ns Dv NULL , 112it will be used to return an error descriptor in case of an error. 113.Pp 114Function 115.Fn dwarf_dieoffset 116retrieves the section-relative offset of the debugging information 117entry referenced by argument 118.Fa die . 119Argument 120.Fa ret_offset 121should point to a location that is to hold the returned 122section-relative offset. 123If argument 124.Fa err 125is 126.No non- Ns Dv NULL , 127it will be used to return an error descriptor in case of an error. 128.Pp 129Function 130.Fn dwarf_get_cu_die_offset_given_cu_header_offset 131returns the offset for the first debugging information entry for a 132compilation unit, given an offset to the header of the compilation 133unit. 134Argument 135.Fa dbg 136should reference a valid debugging context allocated using 137.Xr dwarf_init 3 . 138Argument 139.Fa in_cu_header_offset 140contains the offset to the start of a compilation unit. 141Argument 142.Fa out_cu_die_offset 143points to a location that will hold the returned offset. 144If argument 145.Fa err 146is 147.No non- Ns Dv NULL , 148it will be used to return an error descriptor in case of an error. 149.Pp 150Function 151.Fn dwarf_get_cu_die_offset_given_cu_header_offset_b 152behaves identically to the function 153.Fn dwarf_get_cu_die_offset_given_cu_header_offset 154when the argument 155.Fa is_info 156is non-zero. 157When the argument 158.Fa is_info 159is zero, function 160.Fn dwarf_get_cu_die_offset_given_cu_header_offset_b 161returns the offset for the first debugging information entry for a 162type unit, given an offset to the header of the type unit in argument 163.Fa in_cu_header_offset . 164Argument 165.Fa out_cu_die_offset 166points to a location that will hold the returned offset. 167If the argument 168.Fa err 169is 170.No non- Ns Dv NULL , 171it will be used to return an error descriptor in case of an error. 172.Sh RETURN VALUES 173On success, these functions return 174.Dv DW_DLV_OK . 175In case of an error, these functions return 176.Dv DW_DLV_ERROR 177and set argument 178.Fa err . 179.Pp 180Function 181.Fn dwarf_get_cu_die_offset_given_cu_header_offset 182and 183.Fn dwarf_get_cu_die_offset_given_cu_header_offset_b 184returns 185.Dv DW_DLV_NO_ENTRY 186and sets argument 187.Fa err 188if there is no compilation or type unit located at the 189offset specified in argument 190.Fa in_cu_header_offset . 191.Sh ERRORS 192These functions may fail with the following errors: 193.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" 194.It Bq Er DW_DLE_ARGUMENT 195One of the arguments 196.Va cu_length , 197.Va cu_offset , 198.Va dbg , 199.Va die , 200.Va out_cu_die_offset 201or 202.Va ret_offset 203was 204.Dv NULL . 205.It Bq Er DW_DLE_NO_ENTRY 206Argument 207.Fa in_cu_header_offset 208specified an unknown offset. 209.El 210.Sh SEE ALSO 211.Xr dwarf 3 , 212.Xr dwarf_next_cu_header 3 , 213.Xr dwarf_offdie 3 , 214.Xr dwarf_offdie_b 3 215