1.\" Copyright (c) 2010,2014 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_highpc.3 3092 2014-09-02 22:09:30Z kaiwang27 $ 26.\" 27.Dd July 22, 2014 28.Os 29.Dt DWARF_HIGHPC 3 30.Sh NAME 31.Nm dwarf_arrayorder , 32.Nm dwarf_bitoffset , 33.Nm dwarf_bitsize , 34.Nm dwarf_bytesize , 35.Nm dwarf_highpc , 36.Nm dwarf_highpc_b , 37.Nm dwarf_lowpc , 38.Nm dwarf_srclang 39.Nd retrieve the value of a DWARF attribute 40.Sh LIBRARY 41.Lb libdwarf 42.Sh SYNOPSIS 43.In libdwarf.h 44.Ft int 45.Fo dwarf_arrayorder 46.Fa "Dwarf_Die die" 47.Fa "Dwarf_Unsigned *ret_order" 48.Fa "Dwarf_Error *err" 49.Fc 50.Ft int 51.Fo dwarf_bitoffset 52.Fa "Dwarf_Die die" 53.Fa "Dwarf_Unsigned *ret_size" 54.Fa "Dwarf_Error *err" 55.Fc 56.Ft int 57.Fo dwarf_bitsize 58.Fa "Dwarf_Die die" 59.Fa "Dwarf_Unsigned *ret_size" 60.Fa "Dwarf_Error *err" 61.Fc 62.Ft int 63.Fo dwarf_bytesize 64.Fa "Dwarf_Die die" 65.Fa "Dwarf_Unsigned *ret_size" 66.Fa "Dwarf_Error *err" 67.Fc 68.Ft int 69.Fo dwarf_highpc 70.Fa "Dwarf_Die die" 71.Fa "Dwarf_Addr *ret_highpc" 72.Fa "Dwarf_Error *err" 73.Fc 74.Ft int 75.Fo dwarf_highpc_b 76.Fa "Dwarf_Die die" 77.Fa "Dwarf_Addr *ret_highpc" 78.Fa "Dwarf_Half *ret_form" 79.Fa "enum Dwarf_Form_Class *ret_class" 80.Fa "Dwarf_Error *err" 81.Fc 82.Ft int 83.Fo dwarf_lowpc 84.Fa "Dwarf_Die die" 85.Fa "Dwarf_Addr *ret_lowpc" 86.Fa "Dwarf_Error *err" 87.Fc 88.Ft int 89.Fo dwarf_srclang 90.Fa "Dwarf_Die die" 91.Fa "Dwarf_Unsigned *ret_lang" 92.Fa "Dwarf_Error *err" 93.Fc 94.Sh DESCRIPTION 95These convenience functions are used to retrieve DWARF attribute 96values associated with a Debugging Information Entry (DIE) descriptor 97denoted by argument 98.Ar die . 99These functions store the value of the requested attribute into the 100location pointed to by their second argument, provided that the requested 101attribute exists in the debugging information entry. 102.Pp 103The list of functions and the DWARF attribute that they retrieve are: 104.Pp 105.Bl -tag -width ".Fn dwarf_arrayorder" -compact 106.It Fn dwarf_arrayorder 107Retrieve the 108.Dv DW_AT_ordering 109attribute value. 110.It Fn dwarf_bitoffset 111Retrieve the 112.Dv DW_AT_bit_offset 113attribute value. 114.It Fn dwarf_bitsize 115Retrieve the 116.Dv DW_AT_bit_size 117attribute value. 118.It Fn dwarf_bytesize 119Retrieve the 120.Dv DW_AT_byte_size 121attribute value. 122.It Fn dwarf_highpc 123Retrieve the 124.Dv DW_AT_high_pc 125attribute value. 126.It Fn dwarf_highpc_b 127Retrieve the 128.Dv DW_AT_high_pc 129attribute value. 130.It Fn dwarf_lowpc 131Retrieve the 132.Dv DW_AT_low_pc 133attribute value. 134.It Fn dwarf_srclang 135Retrieve the 136.Dv DW_AT_language 137attribute value. 138.El 139.Pp 140Function 141.Fn dwarf_highpc_b 142is an enhanced version of function 143.Fn dwarf_highpc . 144It sets the location specified by argument 145.Ar ret_form 146to the form code of the attribute 147.Dv DW_AT_high_pc , 148and sets the location specified by argument 149.Ar ret_class 150to the class of that form. 151A value of NULL may be used for either of the arguments 152.Ar ret_form 153or 154.Ar ret_class 155if the caller is not interested in the respective value. 156.Sh RETURN VALUES 157These functions return 158.Dv DW_DLV_OK on success. 159.Pp 160If the debugging information entry descriptor denoted by argument 161.Ar die 162does not contain the requested attribute, these functions return 163.Dv DW_DLV_NO_ENTRY 164and set argument 165.Ar err . 166For other errors, they return 167.Dv DW_DLV_ERROR 168and set argument 169.Ar err . 170.Sh ERRORS 171These functions can fail with the following errors: 172.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" 173.It Bq Er DW_DLE_ARGUMENT 174Arguments 175.Ar die , 176.Ar ret_highpc , 177.Ar ret_lowpc , 178.Ar ret_size , 179.Ar ret_lang 180or 181.Ar ret_order 182were NULL. 183.It Bq Er DW_DLE_NO_ENTRY 184Argument 185.Ar die 186had no requested attribute. 187.El 188.Sh SEE ALSO 189.Xr dwarf 3 , 190.Xr dwarf_attr 3 , 191.Xr dwarf_attrlist 3 , 192.Xr dwarf_hasattr 3 , 193.Xr dwarf_get_form_class 3 194