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_get_abbrev_entry.3 3644 2018-10-15 19:55:01Z jkoshy $ 26.\" 27.Dd April 02, 2011 28.Dt DWARF_GET_ABBREV_ENTRY 3 29.Os 30.Sh NAME 31.Nm dwarf_get_abbrev_entry 32.Nd retrieve attribute information from an abbreviation descriptor 33.Sh LIBRARY 34.Lb libdwarf 35.Sh SYNOPSIS 36.In libdwarf.h 37.Ft int 38.Fo dwarf_get_abbrev_entry 39.Fa "Dwarf_Abbrev abbrev" 40.Fa "Dwarf_Signed ndx" 41.Fa "Dwarf_Half *code" 42.Fa "Dwarf_Signed *form" 43.Fa "Dwarf_Off *offset" 44.Fa "Dwarf_Error *err" 45.Fc 46.Sh DESCRIPTION 47Function 48.Fn dwarf_get_abbrev_entry 49retrieves attribute information from a DWARF abbreviation descriptor. 50.Pp 51Argument 52.Ar abbrev 53should be a valid abbreviation descriptor, as returned by function 54.Xr dwarf_get_abbrev 3 . 55.Pp 56Argument 57.Ar ndx 58specifies the 0-based index of the attribute. 59The total count of the attributes contained in the abbreviation 60entry can be retrieved using the function 61.Xr dwarf_get_abbrev 3 . 62.Pp 63Argument 64.Ar code 65should point to a location which will hold a returned 66attribute code. 67.Pp 68Argument 69.Ar form 70should point to a location which will hold the returned 71form of the attribute. 72.Pp 73Argument 74.Ar offset 75should point to a location which will hold a returned offset, relative 76to the 77.Dq ".debug_abbrev" 78section, for the specified attribute. 79.Pp 80If argument 81.Ar err 82is not NULL, it will be used to return an error descriptor in case 83of an error. 84.Sh RETURN VALUES 85Function 86.Fn dwarf_get_abbrev_entry 87returns 88.Dv DW_DLV_OK 89when it succeeds. 90It returns 91.Dv DW_DLV_NO_ENTRY 92if the attribute index specified by argument 93.Ar ndx 94is out of range. 95In case of an error, it returns 96.Dv DW_DLV_ERROR 97and sets the argument 98.Ar err . 99.Sh EXAMPLES 100To loop through all the attribute entries contained in the 101abbreviation section, use: 102.Bd -literal -offset indent 103Dwarf_Debug dbg; 104Dwarf_Abbrev ab; 105Dwarf_Off aboff, atoff; 106Dwarf_Signed form; 107Dwarf_Half attr; 108Dwarf_Unsigned length, attr_count; 109Dwarf_Error de; 110int i, ret; 111 112/* ...allocate 'dbg' using dwarf_init(3) ... */ 113 114while ((ret = dwarf_next_cu_header(dbg, NULL, NULL, &aboff, 115 NULL, NULL, &de)) == DW_DLV_OK) { 116 while ((ret = dwarf_get_abbrev(dbg, aboff, &ab, &length, 117 &attr_count, &de)) == DW_DLV_OK) { 118 if (length == 1) /* Last entry. */ 119 break; 120 aboff += length; 121 for (i = 0; (Dwarf_Unsigned) i < attr_count; i++) { 122 if (dwarf_get_abbrev_entry(ab, i, 123 &attr, &form, &atoff, &de) != DW_DLV_OK) { 124 warnx("dwarf_get_abbrev_entry failed:" 125 " %s", dwarf_errmsg(de)); 126 continue; 127 } 128 /* .. use the retrieved information ... */ 129 } 130 } 131 132 if (ret != DW_DLV_OK) 133 warnx("dwarf_get_abbrev: %s", dwarf_errmsg(de)); 134} 135 136if (ret == DW_DLV_ERROR) 137 warnx("dwarf_next_cu_header: %s", dwarf_errmsg(de)); 138.Ed 139.Sh ERRORS 140Function 141.Fn dwarf_get_abbrev_entry 142can fail with: 143.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" 144.It Bq Er DW_DLE_ARGUMENT 145One of the arguments 146.Ar abbrev , 147.Ar code , 148.Ar form 149or 150.Ar offset 151was NULL. 152.It Bq Er DW_DLE_NO_ENTRY 153The attribute index specified by argument 154.Ar ndx 155was out of range. 156.El 157.Sh SEE ALSO 158.Xr dwarf 3 , 159.Xr dwarf_get_abbrev 3 160