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