1.\" Copyright (c) 2010 Joseph Koshy 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_formref.3 3640 2018-10-14 14:09:13Z jkoshy $ 26.\" 27.Dd June 21, 2010 28.Dt DWARF_FORMREF 3 29.Os 30.Sh NAME 31.Nm dwarf_formref , 32.Nm dwarf_global_formref 33.Nd retrieve offsets for REFERENCE class attributes 34.Sh LIBRARY 35.Lb libdwarf 36.Sh SYNOPSIS 37.In libdwarf.h 38.Ft int 39.Fo dwarf_formref 40.Fa "Dwarf_Attribute attr" 41.Fa "Dwarf_Off *retoffset" 42.Fa "Dwarf_Error *err" 43.Fc 44.Ft int 45.Fo dwarf_global_formref 46.Fa "Dwarf_Attribute attr" 47.Fa "Dwarf_Off *retoffset" 48.Fa "Dwarf_Error *err" 49.Fc 50.Sh DESCRIPTION 51These functions return the offsets associated with a DWARF attribute 52descriptor. 53.Pp 54Function 55.Fn dwarf_formref 56returns the compilation unit relative offset of the descriptor 57referenced by argument 58.Ar attr 59in the location pointed to by argument 60.Ar retoffset . 61Argument 62.Ar attr 63must be a reference that is local to a compilation unit. 64Permitted forms for argument 65.Ar attr 66are 67.Dv DW_FORM_ref1 , 68.Dv DW_FORM_ref2 , 69.Dv DW_FORM_ref4 , 70.Dv DW_FORM_ref8 71and 72.Dv DW_FORM_ref_udata . 73.Pp 74Function 75.Fn dwarf_global_formref 76returns the section-relative offset of the descriptor referenced by 77argument 78.Ar attr 79in the location pointed to by argument 80.Ar retoffset . 81Argument 82.Ar attr 83should be a legal 84.Sy REFERENCE 85class form. 86Permitted forms for argument 87.Ar attr 88are: 89.Dv DW_FORM_ref_addr , 90.Dv DW_FORM_ref_udata , 91.Dv DW_FORM_ref1 , 92.Dv DW_FORM_ref2 , 93.Dv DW_FORM_ref4 , 94.Dv DW_FORM_ref8 95and 96.Dv DW_FORM_sec_offset . 97The returned offset is relative to the start of the 98.Dq .debug_info 99ELF section. 100.Pp 101If argument 102.Ar err 103is not NULL, it will be used to return an error descriptor in case 104of an error. 105.Sh RETURN VALUES 106These functions return 107.Dv DW_DLV_OK 108on success. 109In case of an error, these functions return 110.Dv DW_DLV_ERROR 111and sets argument 112.Ar err . 113.Sh ERRORS 114These functions may fail with the following errors: 115.Bl -tag -width ".Bq Er DW_DLE_ATTR_FORM_BAD" 116.It Bq Er DW_DLE_ARGUMENT 117Either of arguments 118.Ar attr 119or 120.Ar retoffset 121was NULL. 122.It Bq Er DW_DLE_ATTR_FORM_BAD 123The attribute referenced by argument 124.Ar attr 125was not of a permitted kind. 126.El 127.Sh SEE ALSO 128.Xr dwarf 3 , 129.Xr dwarf_attr 3 , 130.Xr dwarf_formblock 3 , 131.Xr dwarf_formflag 3 , 132.Xr dwarf_formsdata 3 , 133.Xr dwarf_formsig8 3 , 134.Xr dwarf_formstring 3 , 135.Xr dwarf_formudata 3 , 136.Xr dwarf_hasattr 3 137