1.\" Copyright (c) 2010,2014 Kai Wang 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $Id: dwarf_dieoffset.3 3640 2018-10-14 14:09:13Z jkoshy $ 26.\" 27.Dd December 21, 2014 28.Dt DWARF_DIEOFFSET 3 29.Os 30.Sh NAME 31.Nm dwarf_die_CU_offset , 32.Nm dwarf_die_CU_offset_range , 33.Nm dwarf_dieoffset , 34.Nm dwarf_get_cu_die_offset_given_cu_header_offset , 35.Nm dwarf_get_cu_die_offset_given_cu_header_offset_b 36.Nd return offsets of DWARF debugging information entries 37.Sh LIBRARY 38.Lb libdwarf 39.Sh SYNOPSIS 40.In libdwarf.h 41.Ft int 42.Fo dwarf_die_CU_offset 43.Fa "Dwarf_Die die" 44.Fa "Dwarf_Off *ret_offset" 45.Fa "Dwarf_Error *err" 46.Fc 47.Ft int 48.Fo dwarf_die_CU_offset_range 49.Fa "Dwarf_Die die" 50.Fa "Dwarf_Off *cu_offset" 51.Fa "Dwarf_Off *cu_length" 52.Fa "Dwarf_Error *err" 53.Fc 54.Ft int 55.Fo dwarf_dieoffset 56.Fa "Dwarf_Die die" 57.Fa "Dwarf_Off *ret_offset" 58.Fa "Dwarf_Error *err" 59.Fc 60.Ft int 61.Fo dwarf_get_cu_die_offset_given_cu_header_offset 62.Fa "Dwarf_Debug dbg" 63.Fa "Dwarf_Off in_cu_header_offset" 64.Fa "Dwarf_Off *out_cu_die_offset" 65.Fa "Dwarf_Error *err" 66.Fc 67.Ft int 68.Fo dwarf_get_cu_die_offset_given_cu_header_offset_b 69.Fa "Dwarf_Debug dbg" 70.Fa "Dwarf_Off in_cu_header_offset" 71.Fa "Dwarf_Bool is_info" 72.Fa "Dwarf_Off *out_cu_die_offset" 73.Fa "Dwarf_Error *err" 74.Fc 75.Sh DESCRIPTION 76These functions are used to retrieve offsets for DWARF debugging 77information entries. 78.Pp 79Function 80.Fn dwarf_die_CU_offset 81returns the offset of the debugging information entry referenced by 82argument 83.Ar die 84relative to the start of its containing compilation unit. 85Argument 86.Ar ret_offset 87should point to the location that is to hold the returned offset. 88If argument 89.Ar err 90is non-NULL, it will be used to return an error descriptor in case of 91an error. 92.Pp 93Function 94.Fn dwarf_die_CU_offset_range 95returns the section-relative offset and length of the compilation unit 96containing the debugging information entry referenced by argument 97.Ar die . 98Argument 99.Ar cu_offset 100should point to a location that will hold the returned offset. 101Argument 102.Ar cu_length 103should point to a location that will hold the returned length of the 104compilation unit. 105If argument 106.Ar err 107is non-NULL, it will be used to return an error descriptor in case of 108an error. 109.Pp 110Function 111.Fn dwarf_dieoffset 112retrieves the section-relative offset of the debugging information 113entry referenced by argument 114.Ar die . 115Argument 116.Ar ret_offset 117should point to a location that is to hold the returned 118section-relative offset. 119If argument 120.Ar err 121is non-NULL, it will be used to return an error descriptor in case of 122an error. 123.Pp 124Function 125.Fn dwarf_get_cu_die_offset_given_cu_header_offset 126returns the offset for the first debugging information entry for a 127compilation unit, given an offset to the header of the compilation 128unit. 129Argument 130.Ar dbg 131should reference a valid debugging context allocated using 132.Xr dwarf_init 3 . 133Argument 134.Ar in_cu_header_offset 135contains the offset to the start of a compilation unit. 136Argument 137.Ar out_cu_die_offset 138points to a location that will hold the returned offset. 139If argument 140.Ar err 141is non-NULL, it will be used to return an error descriptor in case of 142an error. 143.Pp 144Function 145.Fn dwarf_get_cu_die_offset_given_cu_header_offset_b 146behaves identically to the function 147.Fn dwarf_get_cu_die_offset_given_cu_header_offset 148when the argument 149.Ar is_info 150is non-zero. 151When the argument 152.Ar is_info 153is zero, function 154.Fn dwarf_get_cu_die_offset_given_cu_header_offset_b 155returns the offset for the first debugging information entry for a 156type unit, given an offset to the header of the type unit in argument 157.Ar in_cu_header_offset . 158Argument 159.Ar out_cu_die_offset 160points to a location that will hold the returned offset. 161If the argument 162.Ar err 163is non-NULL, it will be used to return an error descriptor in case of 164an error. 165.Sh RETURN VALUES 166On success, these functions return 167.Dv DW_DLV_OK . 168In case of an error, these functions return 169.Dv DW_DLV_ERROR 170and set argument 171.Ar err . 172.Pp 173Function 174.Fn dwarf_get_cu_die_offset_given_cu_header_offset 175and 176.Fn dwarf_get_cu_die_offset_given_cu_header_offset_b 177returns 178.Dv DW_DLV_NO_ENTRY 179and sets argument 180.Ar err 181if there is no compilation or type unit located at the 182offset specified in argument 183.Ar in_cu_header_offset . 184.Sh ERRORS 185These functions may fail with the following errors: 186.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" 187.It Bq Er DW_DLE_ARGUMENT 188One of the arguments 189.Va cu_length , 190.Va cu_offset , 191.Va dbg , 192.Va die , 193.Va out_cu_die_offset 194or 195.Va ret_offset 196was NULL. 197.It Bq Er DW_DLE_NO_ENTRY 198Argument 199.Ar in_cu_header_offset 200specified an unknown offset. 201.El 202.Sh SEE ALSO 203.Xr dwarf 3 , 204.Xr dwarf_next_cu_header 3 , 205.Xr dwarf_offdie 3 , 206.Xr dwarf_offdie_b 3 207