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 2980 2014-01-21 20:15:54Z kaiwang27 $ 26.\" 27.Dd January 18, 2014 28.Os 29.Dt DWARF_ATTRVAL_SIGNED 3 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 not present in the debugging information entry referenced by 172argument 173.Ar die , 174and if a 175.Dv DW_AT_abstract_origin 176attribute is present in the debugging information entry, 177function 178.Fn dwarf_attrval_unsigned 179will search for the named attribute in the debugging information entry 180referenced by the 181.Dv DW_AT_abstract_origin 182attribute. 183.Sh RETURN VALUES 184On success, these functions returns 185.Dv DW_DLV_OK . 186If the named attribute was not found in the specified debugging 187information entry descriptor these functions return 188.Dv DW_DLV_NO_ENTRY 189and set argument 190.Ar err . 191For other errors, these functions return 192.Dv DW_DLV_ERROR 193and set argument 194.Ar err . 195.Sh COMPATIBILITY 196These functions are extensions added by this implementation of the 197DWARF(3) API. 198.Sh ERRORS 199These functions may fail with the following errors: 200.Bl -tag -width ".Bq Er DW_DLE_ATTR_FORM_BAD" 201.It Bq Er DW_DLE_ARGUMENT 202Either of the arguments 203.Va die 204or 205.Va ret 206was NULL. 207.It Bq Er DW_DLE_NO_ENTRY 208Argument 209.Ar die 210did not contain an attribute corresponding to the value in argument 211.Ar attr . 212.It Bq Er DW_DLE_ATTR_FORM_BAD 213The attribute named by argument 214.Ar attr 215was not of a permitted form. 216.El 217.Sh SEE ALSO 218.Xr dwarf 3 , 219.Xr dwarf_attr 3 , 220.Xr dwarf_hasattr 3 221