1.\" $NetBSD: dwarf_dieoffset.3,v 1.4 2020/11/26 22:51:35 jkoshy 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 3640 2018-10-14 14:09:13Z 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.Ar die 86relative to the start of its containing compilation unit. 87Argument 88.Ar ret_offset 89should point to the location that is to hold the returned offset. 90If argument 91.Ar err 92is non-NULL, it will be used to return an error descriptor in case of 93an error. 94.Pp 95Function 96.Fn dwarf_die_CU_offset_range 97returns the section-relative offset and length of the compilation unit 98containing the debugging information entry referenced by argument 99.Ar die . 100Argument 101.Ar cu_offset 102should point to a location that will hold the returned offset. 103Argument 104.Ar cu_length 105should point to a location that will hold the returned length of the 106compilation unit. 107If argument 108.Ar err 109is non-NULL, it will be used to return an error descriptor in case of 110an error. 111.Pp 112Function 113.Fn dwarf_dieoffset 114retrieves the section-relative offset of the debugging information 115entry referenced by argument 116.Ar die . 117Argument 118.Ar ret_offset 119should point to a location that is to hold the returned 120section-relative offset. 121If argument 122.Ar err 123is non-NULL, it will be used to return an error descriptor in case of 124an error. 125.Pp 126Function 127.Fn dwarf_get_cu_die_offset_given_cu_header_offset 128returns the offset for the first debugging information entry for a 129compilation unit, given an offset to the header of the compilation 130unit. 131Argument 132.Ar dbg 133should reference a valid debugging context allocated using 134.Xr dwarf_init 3 . 135Argument 136.Ar in_cu_header_offset 137contains the offset to the start of a compilation unit. 138Argument 139.Ar out_cu_die_offset 140points to a location that will hold the returned offset. 141If argument 142.Ar err 143is non-NULL, it will be used to return an error descriptor in case of 144an error. 145.Pp 146Function 147.Fn dwarf_get_cu_die_offset_given_cu_header_offset_b 148behaves identically to the function 149.Fn dwarf_get_cu_die_offset_given_cu_header_offset 150when the argument 151.Ar is_info 152is non-zero. 153When the argument 154.Ar is_info 155is zero, function 156.Fn dwarf_get_cu_die_offset_given_cu_header_offset_b 157returns the offset for the first debugging information entry for a 158type unit, given an offset to the header of the type unit in argument 159.Ar in_cu_header_offset . 160Argument 161.Ar out_cu_die_offset 162points to a location that will hold the returned offset. 163If the argument 164.Ar err 165is non-NULL, it will be used to return an error descriptor in case of 166an error. 167.Sh RETURN VALUES 168On success, these functions return 169.Dv DW_DLV_OK . 170In case of an error, these functions return 171.Dv DW_DLV_ERROR 172and set argument 173.Ar err . 174.Pp 175Function 176.Fn dwarf_get_cu_die_offset_given_cu_header_offset 177and 178.Fn dwarf_get_cu_die_offset_given_cu_header_offset_b 179returns 180.Dv DW_DLV_NO_ENTRY 181and sets argument 182.Ar err 183if there is no compilation or type unit located at the 184offset specified in argument 185.Ar in_cu_header_offset . 186.Sh ERRORS 187These functions may fail with the following errors: 188.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" 189.It Bq Er DW_DLE_ARGUMENT 190One of the arguments 191.Va cu_length , 192.Va cu_offset , 193.Va dbg , 194.Va die , 195.Va out_cu_die_offset 196or 197.Va ret_offset 198was NULL. 199.It Bq Er DW_DLE_NO_ENTRY 200Argument 201.Ar in_cu_header_offset 202specified an unknown offset. 203.El 204.Sh SEE ALSO 205.Xr dwarf 3 , 206.Xr dwarf_next_cu_header 3 , 207.Xr dwarf_offdie 3 , 208.Xr dwarf_offdie_b 3 209