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