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