1.\" Copyright (c) 2011 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_get_types.3 3640 2018-10-14 14:09:13Z jkoshy $ 26.\" 27.Dd April 10, 2011 28.Dt DWARF_GET_TYPES 3 29.Os 30.Sh NAME 31.Nm dwarf_get_types , 32.Nm dwarf_type_cu_offset , 33.Nm dwarf_type_die_offset , 34.Nm dwarf_type_name_offsets , 35.Nm dwarf_typename 36.Nd retrieve information about user-defined types 37.Sh LIBRARY 38.Lb libdwarf 39.Sh SYNOPSIS 40.In libdwarf.h 41.Ft int 42.Fo dwarf_get_types 43.Fa "Dwarf_Debug dbg" 44.Fa "Dwarf_Type **types" 45.Fa "Dwarf_Signed *ntypes" 46.Fa "Dwarf_Error *err" 47.Fc 48.Ft int 49.Fo dwarf_type_cu_offset 50.Fa "Dwarf_Type type" 51.Fa "Dwarf_Off *cu_offset" 52.Fa "Dwarf_Error *err" 53.Fc 54.Ft int 55.Fo dwarf_type_die_offset 56.Fa "Dwarf_Type type" 57.Fa "Dwarf_Off *die_offset" 58.Fa "Dwarf_Error *err" 59.Fc 60.Ft int 61.Fo dwarf_type_name_offsets 62.Fa "Dwarf_Type type" 63.Fa "char **name" 64.Fa "Dwarf_Off *die_offset" 65.Fa "Dwarf_Off *cu_die_offset" 66.Fa "Dwarf_Error *err" 67.Fc 68.Ft int 69.Fo dwarf_typename 70.Fa "Dwarf_Type type" 71.Fa "char **name" 72.Fa "Dwarf_Error *err" 73.Fc 74.Sh DESCRIPTION 75These APIs retrieve information about user-defined types from the 76SGI-specific 77.Dq ".debug_typenames" 78section. 79.Pp 80Standards-conformant applications should use the functions 81.Xr dwarf_get_pubtypes 3 , 82.Xr dwarf_pubtype_cu_offset 3 , 83.Xr dwarf_pubtype_die_offset 3 , 84.Xr dwarf_pubtype_name_offsets 3 85and 86.Xr dwarf_pubtypename 3 , 87which operate on the equivalent 88.Dq ".debug_pubtypes" 89section defined by the DWARF3 standard. 90.Pp 91Information about user-defined types is returned using opaque descriptors 92of type 93.Vt Dwarf_Type . 94Applications need to use the functions described below to retrieve 95the name and offset information contained in these descriptors. 96.Pp 97Function 98.Fn dwarf_get_types 99retrieves descriptors for all user-defined types associated with the 100DWARF debug context specified by argument 101.Ar dbg . 102The argument 103.Ar types 104should point to a location that will be set to a pointer to an array 105of 106.Vt Dwarf_Type 107descriptors. 108The argument 109.Ar ntypes 110should point to a location that will be set to the number of 111descriptors returned. 112.Pp 113Function 114.Fn dwarf_type_cu_offset 115returns the offset, relative to the 116.Dq ".debug_info" 117section, of the compilation unit that contains the debugging 118information entry associated with the argument 119.Ar type . 120Argument 121.Ar cu_offset 122should point to a location that will hold the returned offset. 123.Pp 124Function 125.Fn dwarf_type_die_offset 126retrieves the offset, relative to the 127.Dq ".debug_info" 128section, of the debugging information entry associated with the 129argument 130.Ar type , 131and stores it into the location pointed to by the argument 132.Ar die_offset . 133.Pp 134Function 135.Fn dwarf_type_name_offsets 136retrieves the name and offsets for the debugging information 137entry for argument 138.Ar type . 139Argument 140.Ar name 141should point to a location which will be set to a pointer to a 142NUL-terminated string containing the name of the associated debugging 143information entry. 144Argument 145.Ar die_offset 146should point to a location which will be set to the offset, relative 147to the 148.Dq ".debug_info" 149section, of the associated debugging information entry. 150Argument 151.Ar cu_die_offset 152should point to a location which will be set to a offset, relative to 153the 154.Dq ".debug_info" 155section, of the first debugging information entry in the compilation 156unit associated with argument 157.Ar type . 158.Pp 159Function 160.Fn dwarf_typename 161sets the location pointed to by argument 162.Ar name 163to a pointer to a NUL-terminated string holding the name of the 164debugging information entry associated with the argument 165.Ar type . 166.Ss Memory Management 167The memory area used for the array of 168.Vt Dwarf_Type 169descriptors returned in argument 170.Ar types 171by function 172.Fn dwarf_get_types 173is owned by the 174.Lb libdwarf . 175Application code should not attempt to directly free this pointer. 176Portable code should instead use the function 177.Xr dwarf_types_dealloc 3 178to indicate that the memory area may be freed. 179.Pp 180The memory area used for the string returned in the 181.Ar name 182argument to functions 183.Fn dwarf_type_name_offsets 184and 185.Fn dwarf_typename 186is owned by the 187.Lb libdwarf . 188Portable code should indicate that the memory area can 189be freed using the 190.Xr dwarf_dealloc 3 191function. 192.Ss Error Returns 193If argument 194.Ar err 195is not NULL, these functions will use it to store error information, 196in case of an error. 197.Sh RETURN VALUES 198On success, these functions returns 199.Dv DW_DLV_OK . 200In case of an error, they return 201.Dv DW_DLV_ERROR 202and set the argument 203.Ar err . 204.Sh ERRORS 205These functions may fail with the following errors: 206.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" 207.It Bq Er DW_DLE_ARGUMENT 208One of the arguments 209.Va cu_die_offset , 210.Va cu_offset , 211.Va dbg , 212.Va die_offset , 213.Va type , 214.Va types , 215.Va name , 216or 217.Va ntypes 218was NULL. 219.It Bq Er DW_DLE_NO_ENTRY 220The DWARF debugging context referenced by argument 221.Ar dbg 222did not contain information about user-defined types. 223.El 224.Sh SEE ALSO 225.Xr dwarf 3 , 226.Xr dwarf_get_cu_die_offset_given_cu_header_offset 3 , 227.Xr dwarf_get_pubtypes 3 , 228.Xr dwarf_pubtype_cu_offset 3 , 229.Xr dwarf_pubtype_die_offset 3 , 230.Xr dwarf_pubtype_name_offsets 3 , 231.Xr dwarf_pubtypename 3 , 232.Xr dwarf_types_dealloc 3 233