1.\" $NetBSD: dwarf_get_globals.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_globals.3 2071 2011-10-27 03:20:00Z jkoshy 28.\" 29.Dd April 2, 2011 30.Os 31.Dt DWARF_GET_GLOBALS 3 32.Sh NAME 33.Nm dwarf_get_globals , 34.Nm dwarf_global_cu_offset , 35.Nm dwarf_global_die_offset , 36.Nm dwarf_global_name_offsets , 37.Nm dwarf_globname 38.Nd retrieve information about global objects 39.Sh LIBRARY 40.Lb libdwarf 41.Sh SYNOPSIS 42.In libdwarf.h 43.Ft int 44.Fo dwarf_get_globals 45.Fa "Dwarf_Debug dbg" 46.Fa "Dwarf_Global **globals" 47.Fa "Dwarf_Signed *nglobals" 48.Fa "Dwarf_Error *err" 49.Fc 50.Ft int 51.Fo dwarf_global_cu_offset 52.Fa "Dwarf_Global global" 53.Fa "Dwarf_Off *cu_offset" 54.Fa "Dwarf_Error *err" 55.Fc 56.Ft int 57.Fo dwarf_global_die_offset 58.Fa "Dwarf_Global global" 59.Fa "Dwarf_Off *die_offset" 60.Fa "Dwarf_Error *err" 61.Fc 62.Ft int 63.Fo dwarf_global_name_offsets 64.Fa "Dwarf_Global global" 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_globname 72.Fa "Dwarf_Global global" 73.Fa "char **name" 74.Fa "Dwarf_Error *err" 75.Fc 76.Sh DESCRIPTION 77These functions retrieve information about global symbols from the 78lookup tables in the 79.Dq ".debug_pubnames" 80DWARF section. 81Information about these global symbols is returned using opaque descriptors 82of type 83.Vt Dwarf_Global . 84Applications need to use the functions described below to retrieve the 85name and the offsets for these descriptors. 86.Pp 87Function 88.Fn dwarf_get_globals 89retrieves descriptors for all the global symbols associated with the 90DWARF debug context specified by argument 91.Ar dbg . 92The argument 93.Ar globals 94should point to a location that will be set to a pointer to an array 95of 96.Vt Dwarf_Global 97descriptors. 98The argument 99.Ar nglobals 100should point to a location that will be set to the number of 101descriptors returned. 102.Pp 103Function 104.Fn dwarf_global_cu_offset 105returns the section-relative 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 global . 110Argument 111.Ar cu_offset 112should point to a location that will hold the returned offset. 113.Pp 114Function 115.Fn dwarf_global_die_offset 116retrieves the section-relative offset, relative to the 117.Dq ".debug_info" 118section, of the debugging information entry associated with the 119argument 120.Ar global , 121and stores it into the location pointed to by the argument 122.Ar die_offset . 123.Pp 124Function 125.Fn dwarf_global_name_offsets 126retrieves the name and the offsets for the debugging information 127entry for argument 128.Ar global . 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 a section-relative 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 a 143section-relative offset, relative to the 144.Dq ".debug_info" 145section, of the first debugging information entry in 146the compilation unit associated with argument 147.Ar global . 148.Pp 149Function 150.Fn dwarf_globname 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 global . 156.Ss Memory Management 157The memory area used for the array of 158.Vt Dwarf_Global 159descriptors returned in argument 160.Ar globals 161by function 162.Fn dwarf_get_globals 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_globals_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_globname 174and 175.Fn dwarf_global_name_offsets 176is owned by the 177.Lb libdwarf . 178Portable code should use the 179.Xr dwarf_dealloc 3 180function to indicate that the memory area may be freed. 181.Ss Error Returns 182If argument 183.Ar err 184is not NULL, these functions will use it to store error information, 185in case of an error. 186.Sh RETURN VALUES 187On success, these functions returns 188.Dv DW_DLV_OK . 189In case of an error, they return 190.Dv DW_DLV_ERROR 191and set the argument 192.Ar err . 193.Sh ERRORS 194These functions may fail with the following errors: 195.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" 196.It Bq Er DW_DLE_ARGUMENT 197One of the arguments 198.Va cu_die_offset , 199.Va cu_offset , 200.Va dbg , 201.Va die_offset , 202.Va global , 203.Va globals , 204.Va name , 205or 206.Va nglobals 207was NULL. 208.El 209.Sh SEE ALSO 210.Xr dwarf 3 , 211.Xr dwarf_dealloc 3 , 212.Xr dwarf_get_cu_die_offset_given_cu_header_offset 3 , 213.Xr dwarf_globals_dealloc 3 214