1 .\" Copyright (c) 2010,2014 Kai Wang
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
25 .\" $Id: dwarf_dieoffset.3 3640 2018-10-14 14:09:13Z jkoshy $
31 .Nm dwarf_die_CU_offset ,
32 .Nm dwarf_die_CU_offset_range ,
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
42 .Fo dwarf_die_CU_offset
44 .Fa "Dwarf_Off *ret_offset"
45 .Fa "Dwarf_Error *err"
48 .Fo dwarf_die_CU_offset_range
50 .Fa "Dwarf_Off *cu_offset"
51 .Fa "Dwarf_Off *cu_length"
52 .Fa "Dwarf_Error *err"
57 .Fa "Dwarf_Off *ret_offset"
58 .Fa "Dwarf_Error *err"
61 .Fo dwarf_get_cu_die_offset_given_cu_header_offset
63 .Fa "Dwarf_Off in_cu_header_offset"
64 .Fa "Dwarf_Off *out_cu_die_offset"
65 .Fa "Dwarf_Error *err"
68 .Fo dwarf_get_cu_die_offset_given_cu_header_offset_b
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"
76 These functions are used to retrieve offsets for DWARF debugging
80 .Fn dwarf_die_CU_offset
81 returns the offset of the debugging information entry referenced by
84 relative to the start of its containing compilation unit.
87 should point to the location that is to hold the returned offset.
90 is non-NULL, it will be used to return an error descriptor in case of
94 .Fn dwarf_die_CU_offset_range
95 returns the section-relative offset and length of the compilation unit
96 containing the debugging information entry referenced by argument
100 should point to a location that will hold the returned offset.
103 should point to a location that will hold the returned length of the
107 is non-NULL, it will be used to return an error descriptor in case of
112 retrieves the section-relative offset of the debugging information
113 entry referenced by argument
117 should point to a location that is to hold the returned
118 section-relative offset.
121 is non-NULL, it will be used to return an error descriptor in case of
125 .Fn dwarf_get_cu_die_offset_given_cu_header_offset
126 returns the offset for the first debugging information entry for a
127 compilation unit, given an offset to the header of the compilation
131 should reference a valid debugging context allocated using
134 .Ar in_cu_header_offset
135 contains the offset to the start of a compilation unit.
137 .Ar out_cu_die_offset
138 points to a location that will hold the returned offset.
141 is non-NULL, it will be used to return an error descriptor in case of
145 .Fn dwarf_get_cu_die_offset_given_cu_header_offset_b
146 behaves identically to the function
147 .Fn dwarf_get_cu_die_offset_given_cu_header_offset
154 .Fn dwarf_get_cu_die_offset_given_cu_header_offset_b
155 returns the offset for the first debugging information entry for a
156 type unit, given an offset to the header of the type unit in argument
157 .Ar in_cu_header_offset .
159 .Ar out_cu_die_offset
160 points to a location that will hold the returned offset.
163 is non-NULL, it will be used to return an error descriptor in case of
166 On success, these functions return
168 In case of an error, these functions return
174 .Fn dwarf_get_cu_die_offset_given_cu_header_offset
176 .Fn dwarf_get_cu_die_offset_given_cu_header_offset_b
181 if there is no compilation or type unit located at the
182 offset specified in argument
183 .Ar in_cu_header_offset .
185 These functions may fail with the following errors:
186 .Bl -tag -width ".Bq Er DW_DLE_ARGUMENT"
187 .It Bq Er DW_DLE_ARGUMENT
193 .Va out_cu_die_offset
197 .It Bq Er DW_DLE_NO_ENTRY
199 .Ar in_cu_header_offset
200 specified an unknown offset.
204 .Xr dwarf_next_cu_header 3 ,