1.\" Copyright (c) 2010 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 2073 2011-10-27 03:30:47Z jkoshy $ 26.\" 27.Dd April 17, 2010 28.Os 29.Dt DWARF_DIEOFFSET 3 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.Nd return offsets of DWARF debugging information entries 36.Sh LIBRARY 37.Lb libdwarf 38.Sh SYNOPSIS 39.In libdwarf.h 40.Ft int 41.Fo dwarf_die_CU_offset 42.Fa "Dwarf_Die die" 43.Fa "Dwarf_Off *ret_offset" 44.Fa "Dwarf_Error *err" 45.Fc 46.Ft int 47.Fo dwarf_die_CU_offset_range 48.Fa "Dwarf_Die die" 49.Fa "Dwarf_Off *cu_offset" 50.Fa "Dwarf_Off *cu_length" 51.Fa "Dwarf_Error *err" 52.Fc 53.Ft int 54.Fo dwarf_dieoffset 55.Fa "Dwarf_Die die" 56.Fa "Dwarf_Off *ret_offset" 57.Fa "Dwarf_Error *err" 58.Fc 59.Ft int 60.Fo dwarf_get_cu_die_offset_given_cu_header_offset 61.Fa "Dwarf_Debug dbg" 62.Fa "Dwarf_Off in_cu_header_offset" 63.Fa "Dwarf_Off *out_cu_die_offset" 64.Fa "Dwarf_Error *err" 65.Fc 66.Sh DESCRIPTION 67These functions are used to retrieve offsets for DWARF debugging 68information entries. 69.Pp 70Function 71.Fn dwarf_die_CU_offset 72returns the offset of the debugging information entry referenced by 73argument 74.Ar die 75relative to the start of its containing compilation unit. 76Argument 77.Ar ret_offset 78should point to the location that is to hold the returned offset. 79If argument 80.Ar err 81is non-NULL, it will be used to return an error descriptor in case of 82an error. 83.Pp 84Function 85.Fn dwarf_die_CU_offset_range 86returns the section-relative offset and length of the compilation unit 87containing the debugging information entry referenced by argument 88.Ar die . 89Argument 90.Ar cu_offset 91should point to a location that will hold the returned offset. 92Argument 93.Ar cu_length 94should point to a location that will hold the returned length of the 95compilation unit. 96If argument 97.Ar err 98is non-NULL, it will be used to return an error descriptor in case of 99an error. 100.Pp 101Function 102.Fn dwarf_dieoffset 103retrieves the section-relative offset of the debugging information 104entry referenced by argument 105.Ar die . 106Argument 107.Ar ret_offset 108should point to a location that is to hold the returned 109section-relative offset. 110If argument 111.Ar err 112is non-NULL, it will be used to return an error descriptor in case of 113an error. 114.Pp 115Function 116.Fn dwarf_get_cu_die_offset_given_cu_header_offset 117returns the offset for the debugging information entry for a 118compilation unit, given an offset to the header of the compilation 119unit. 120Argument 121.Ar dbg 122should reference a valid debugging context allocated using 123.Xr dwarf_init 3 . 124Argument 125.Ar in_cu_header_offset 126contains the offset to the start of a compilation unit. 127Argument 128.Ar out_cu_die_offset 129points to a location that will hold the returned offset. 130If argument 131.Ar err 132is non-NULL, it will be used to return an error descriptor in case of 133an error. 134.Sh RETURN VALUES 135On success, these functions returns 136.Dv DW_DLV_OK . 137In case of an error, these functions return 138.Dv DW_DLV_ERROR 139and set argument 140.Ar err . 141.Pp 142Function 143.Fn dwarf_get_cu_die_offset_given_cu_header_offset 144returns 145.Dv DW_DLV_NO_ENTRY 146and sets argument 147.Ar err 148if there is no compilation unit located at the 149offset specified in argument 150.Ar in_cu_header_offset . 151.Sh ERRORS 152These functions may fail with the following errors: 153.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" 154.It Bq Er DW_DLE_ARGUMENT 155One of the arguments 156.Va cu_length , 157.Va cu_offset , 158.Va dbg , 159.Va die , 160.Va out_cu_die_offset 161or 162.Va ret_offset 163was NULL. 164.It Bq Er DW_DLE_NO_ENTRY 165Argument 166.Ar in_cu_header_offset 167specified an unknown offset. 168.El 169.Sh SEE ALSO 170.Xr dwarf 3 , 171.Xr dwarf_next_cu_header 3 , 172.Xr dwarf_offdie 3 173