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 2071 2011-10-27 03:20:00Z jkoshy $ 26.\" 27.Dd April 02, 2011 28.Os 29.Dt DWARF_GET_ABBREV_ENTRY 3 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 ERRORS 100Function 101.Fn dwarf_get_abbrev_entry 102can fail with: 103.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" 104.It Bq Er DW_DLE_ARGUMENT 105One of the arguments 106.Ar abbrev , 107.Ar code , 108.Ar form 109or 110.Ar offset 111was NULL. 112.It Bq Er DW_DLE_NO_ENTRY 113The attribute index specified by argument 114.Ar ndx 115was out of range. 116.El 117.Sh EXAMPLE 118To loop through all the attribute entries contained in the 119abbreviation section, use: 120.Bd -literal -offset indent 121Dwarf_Debug dbg; 122Dwarf_Abbrev ab; 123Dwarf_Off aboff, atoff; 124Dwarf_Signed form; 125Dwarf_Half attr; 126Dwarf_Unsigned length, attr_count; 127Dwarf_Error de; 128int i, ret; 129 130/* ...allocate 'dbg' using dwarf_init(3) ... */ 131 132while ((ret = dwarf_next_cu_header(dbg, NULL, NULL, &aboff, 133 NULL, NULL, &de)) == DW_DLV_OK) { 134 while ((ret = dwarf_get_abbrev(dbg, aboff, &ab, &length, 135 &attr_count, &de)) == DW_DLV_OK) { 136 if (length == 1) /* Last entry. */ 137 break; 138 aboff += length; 139 for (i = 0; (Dwarf_Unsigned) i < attr_count; i++) { 140 if (dwarf_get_abbrev_entry(ab, i, 141 &attr, &form, &atoff, &de) != DW_DLV_OK) { 142 warnx("dwarf_get_abbrev_entry failed:" 143 " %s", dwarf_errmsg(de)); 144 continue; 145 } 146 /* .. use the retrieved information ... */ 147 } 148 } 149 150 if (ret != DW_DLV_OK) 151 warnx("dwarf_get_abbrev: %s", dwarf_errmsg(de)); 152} 153 154if (ret == DW_DLV_ERROR) 155 warnx("dwarf_next_cu_header: %s", dwarf_errmsg(de)); 156.Ed 157.Sh SEE ALSO 158.Xr dwarf 3 , 159.Xr dwarf_get_abbrev 3 160