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_attrval_signed.3 3640 2018-10-14 14:09:13Z jkoshy $ 26.\" 27.Dd December 26, 2016 28.Dt DWARF_ATTRVAL_SIGNED 3 29.Os 30.Sh NAME 31.Nm dwarf_attrval_flag , 32.Nm dwarf_attrval_signed , 33.Nm dwarf_attrval_string , 34.Nm dwarf_attrval_unsigned 35.Nd retrieve the value of an attribute within a DWARF debugging information entry 36.Sh LIBRARY 37.Lb libdwarf 38.Sh SYNOPSIS 39.In libdwarf.h 40.Ft int 41.Fo dwarf_attrval_flag 42.Fa "Dwarf_Die die" 43.Fa "Dwarf_Half attr" 44.Fa "Dwarf_Bool *ret" 45.Fa "Dwarf_Error *err" 46.Fc 47.Ft int 48.Fo dwarf_attrval_signed 49.Fa "Dwarf_Die die" 50.Fa "Dwarf_Half attr" 51.Fa "Dwarf_Signed *ret" 52.Fa "Dwarf_Error *err" 53.Fc 54.Ft int 55.Fo dwarf_attrval_string 56.Fa "Dwarf_Die die" 57.Fa "Dwarf_Half attr" 58.Fa "const char **ret" 59.Fa "Dwarf_Error *err" 60.Fc 61.Ft int 62.Fo dwarf_attrval_unsigned 63.Fa "Dwarf_Die die" 64.Fa "Dwarf_Half attr" 65.Fa "Dwarf_Unsigned *ret" 66.Fa "Dwarf_Error *err" 67.Fc 68.Sh DESCRIPTION 69These functions search the debugging information entry referenced 70by argument 71.Ar die 72for the attribute named by argument 73.Ar attr . 74If the named attribute is found, the functions set the location 75pointed to by argument 76.Ar ret 77to the value of the attribute. 78The argument 79.Ar err , 80if non NULL, 81will be used to return an error descriptor in case of an error. 82.Pp 83Function 84.Fn dwarf_attrval_flag 85sets the location pointed to by argument 86.Ar ret 87to either 0 or 1. If the form of the attribute named by argument 88.Ar attr 89is 90.Dv DW_FORM_flag , 91function 92.Fn dwarf_attrval_flag 93sets the location pointed to by argument 94.Ar ret 95to 1 if the attribute has a non-zero value, or to 0 otherwise. 96If the form of the attribute named by argument 97.Ar attr 98is 99.Dv DW_FORM_flag_present , 100function 101.Fn dwarf_attrval_flag 102unconditionally sets the location pointed to by argument 103.Ar ret 104to 1. 105The form of the attribute must be one of 106.Dv DW_FORM_flag 107or 108.Dv DW_FORM_flag_present . 109.Pp 110Function 111.Fn dwarf_attrval_signed 112stores the value for the attribute named by argument 113.Ar attr , 114into the location pointed to by argument 115.Ar ret . 116The attribute's value is treated as a signed integral quantity and is 117sign-extended as needed. 118The attribute named by the argument 119.Ar attr 120must belong to the 121.Dv CONSTANT 122class and must have one of the following forms: 123.Dv DW_FORM_data1 , 124.Dv DW_FORM_data2 , 125.Dv DW_FORM_data4 , 126.Dv DW_FORM_data8 127or 128.Dv DW_FORM_sdata . 129.Pp 130Function 131.Fn dwarf_attrval_string 132sets the location pointed to by argument 133.Ar ret 134to a pointer to a NUL-terminated string that is the value of the 135attribute named by argument 136.Ar attr . 137The form of the attribute must be one of 138.Dv DW_FORM_string 139or 140.Dv DW_FORM_strp . 141.Pp 142Function 143.Fn dwarf_attrval_unsigned 144stores the value for the attribute named by argument 145.Ar attr 146into the location pointed to by argument 147.Ar ret . 148The attribute's value is treated as an unsigned integral quantity, and 149is zero-extended as needed. 150The named attribute must belong to one of the 151.Dv CONSTANT , 152.Dv ADDRESS 153or 154.Dv REFERENCE 155classes and must have one of the following forms: 156.Dv DW_FORM_addr , 157.Dv DW_FORM_data1 , 158.Dv DW_FORM_data2 , 159.Dv DW_FORM_data4 , 160.Dv DW_FORM_data8 , 161.Dv DW_FORM_udata , 162.Dv DW_FORM_ref1 , 163.Dv DW_FORM_ref2 , 164.Dv DW_FORM_ref4 , 165.Dv DW_FORM_ref8 , 166or 167.Dv DW_FORM_ref_udata . 168.Pp 169If the attribute named by argument 170.Ar attr 171is 172.Dv DW_AT_type 173and is not present in the debugging information entry referenced by argument 174.Ar die , 175and if a 176.Dv DW_AT_abstract_origin 177or 178.Dv DW_AT_specification 179attribute is present in the debugging information entry, 180function 181.Fn dwarf_attrval_unsigned 182will search for the named attribute in the debugging information entry 183referenced by the 184.Dv DW_AT_abstract_origin 185or 186.Dv DW_AT_specification 187attribute. 188.Sh RETURN VALUES 189On success, these functions returns 190.Dv DW_DLV_OK . 191If the named attribute was not found in the specified debugging 192information entry descriptor these functions return 193.Dv DW_DLV_NO_ENTRY 194and set argument 195.Ar err . 196For other errors, these functions return 197.Dv DW_DLV_ERROR 198and set argument 199.Ar err . 200.Sh COMPATIBILITY 201These functions are extensions added by this implementation of the 202DWARF(3) API. 203.Sh ERRORS 204These functions may fail with the following errors: 205.Bl -tag -width ".Bq Er DW_DLE_ATTR_FORM_BAD" 206.It Bq Er DW_DLE_ARGUMENT 207Either of the arguments 208.Va die 209or 210.Va ret 211was NULL. 212.It Bq Er DW_DLE_NO_ENTRY 213Argument 214.Ar die 215did not contain an attribute corresponding to the value in argument 216.Ar attr . 217.It Bq Er DW_DLE_ATTR_FORM_BAD 218The attribute named by argument 219.Ar attr 220was not of a permitted form. 221.El 222.Sh SEE ALSO 223.Xr dwarf 3 , 224.Xr dwarf_attr 3 , 225.Xr dwarf_hasattr 3 226