1.\" $NetBSD: dwarf_get_weaks.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_weaks.3 2071 2011-10-27 03:20:00Z jkoshy 28.\" 29.Dd April 10, 2011 30.Os 31.Dt DWARF_GET_WEAKS 3 32.Sh NAME 33.Nm dwarf_get_weaks , 34.Nm dwarf_weak_cu_offset , 35.Nm dwarf_weak_die_offset , 36.Nm dwarf_weak_name_offsets , 37.Nm dwarf_weakname 38.Nd retrieve information about weak symbols 39.Sh LIBRARY 40.Lb libdwarf 41.Sh SYNOPSIS 42.In libdwarf.h 43.Ft int 44.Fo dwarf_get_weaks 45.Fa "Dwarf_Debug dbg" 46.Fa "Dwarf_Weak **weaks" 47.Fa "Dwarf_Signed *nweaks" 48.Fa "Dwarf_Error *err" 49.Fc 50.Ft int 51.Fo dwarf_weak_cu_offset 52.Fa "Dwarf_Weak weak" 53.Fa "Dwarf_Off *cu_offset" 54.Fa "Dwarf_Error *err" 55.Fc 56.Ft int 57.Fo dwarf_weak_die_offset 58.Fa "Dwarf_Weak weak" 59.Fa "Dwarf_Off *die_offset" 60.Fa "Dwarf_Error *err" 61.Fc 62.Ft int 63.Fo dwarf_weak_name_offsets 64.Fa "Dwarf_Weak weak" 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_weakname 72.Fa "Dwarf_Weak weak" 73.Fa "char **name" 74.Fa "Dwarf_Error *err" 75.Fc 76.Sh DESCRIPTION 77These functions retrieve information about weak symbols from the 78lookup tables in the (SGI-specific) 79.Dq ".debug_weaknames" 80section. 81Information about weak symbols is returned using opaque descriptors 82of type 83.Vt Dwarf_Weak . 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_weaks 89retrieves descriptors for all the weak symbols associated with the 90DWARF debug context specified by argument 91.Ar dbg . 92The argument 93.Ar weaks 94should point to a location that will be set to a pointer to an array 95of 96.Vt Dwarf_Weak 97descriptors. 98The argument 99.Ar nweaks 100should point to a location that will be set to the number of 101descriptors returned. 102.Pp 103Function 104.Fn dwarf_weak_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 weak . 110Argument 111.Ar cu_offset 112should point to a location that will hold the returned offset. 113.Pp 114Function 115.Fn dwarf_weak_die_offset 116retrieves the offset, relative to the 117.Dq ".debug_info" 118section, of the debugging information entry associated with the 119argument 120.Ar weak , 121and stores it into the location pointed to by the argument 122.Ar die_offset . 123.Pp 124Function 125.Fn dwarf_weak_name_offsets 126retrieves the name and offsets for the debugging information 127entry for argument 128.Ar weak . 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 offset, relative 137to 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 weak . 148.Pp 149Function 150.Fn dwarf_weakname 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 weak . 156.Ss Memory Management 157The memory area used for the array of 158.Vt Dwarf_Weak 159descriptors returned in argument 160.Ar weaks 161by function 162.Fn dwarf_get_weaks 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_weaks_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_weak_name_offsets 174and 175.Fn dwarf_weakname 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 ERRORS 195These functions may fail with the following errors: 196.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" 197.It Bq Er DW_DLE_ARGUMENT 198One of the arguments 199.Va cu_die_offset , 200.Va cu_offset , 201.Va dbg , 202.Va die_offset , 203.Va weak , 204.Va weaks , 205.Va name , 206or 207.Va nweaks 208was NULL. 209.It Bq Er DW_DLE_NO_ENTRY 210The DWARF debugging context referenced by argument 211.Ar dbg 212did not contain information about weak symbols. 213.El 214.Sh SEE ALSO 215.Xr dwarf 3 , 216.Xr dwarf_get_cu_die_offset_given_cu_header_offset 3 , 217.Xr dwarf_weaks_dealloc 3 218