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.3 3644 2018-10-15 19:55:01Z jkoshy $
26.\"
27.Dd March 27, 2011
28.Dt DWARF_GET_ABBREV 3
29.Os
30.Sh NAME
31.Nm dwarf_get_abbrev
32.Nd retrieve abbreviation information
33.Sh LIBRARY
34.Lb libdwarf
35.Sh SYNOPSIS
36.In libdwarf.h
37.Ft int
38.Fo dwarf_get_abbrev
39.Fa "Dwarf_Debug dbg"
40.Fa "Dwarf_Unsigned offset"
41.Fa "Dwarf_Abbrev *ret_abbrev"
42.Fa "Dwarf_Unsigned *length"
43.Fa "Dwarf_Unsigned *attr_count"
44.Fa "Dwarf_Error *err"
45.Fc
46.Sh DESCRIPTION
47Function
48.Fn dwarf_get_abbrev
49retrieves information about an abbreviation from the DWARF abbreviations
50section,
51.Dq ".debug_abbrev" .
52Abbreviation information is returned using an opaque descriptor
53of type
54.Vt Dwarf_Abbrev .
55The returned
56.Vt Dwarf_Abbrev
57descriptor may then be passed to the other abbreviation related APIs
58in the DWARF(3) API to retrieve specific information about the
59abbreviation.
60.Pp
61Argument
62.Ar dbg
63should reference a DWARF debug context allocated using
64.Xr dwarf_init 3 .
65.Pp
66Argument
67.Ar offset
68should be an offset, relative to the
69.Dq ".debug_abbrev"
70section, to the start of an abbreviation entry.
71.Pp
72Argument
73.Ar ret_abbrev
74should point to a location that will hold a pointer to the
75returned
76.Vt Dwarf_Abbrev
77descriptor.
78.Pp
79Argument
80.Ar length
81should point to a location that will hold the number of bytes used
82by the abbrevation in the DWARF
83.Dq ".debug_abbrev"
84section.
85.Pp
86Argument
87.Ar attr_count
88should point to a location that will hold the number of
89attributes in the abbrevation.
90.Pp
91If argument
92.Ar err
93is not NULL, it will be used to store error information in case of an
94error.
95.Ss Memory Management
96The memory area used for the
97.Vt Dwarf_Abbrev
98descriptor returned in argument
99.Ar ret_abbrev
100is allocated by the
101.Lb libdwarf .
102Application code should use function
103.Fn dwarf_dealloc
104with the allocation type
105.Dv DW_DLA_ABBREV
106to free the memory area when the
107.Vt Dwarf_Abbrev
108descriptor is no longer needed.
109.Ss Application Programming Notes
110The last abbreviation entry in a standard DWARF abbreviation section
111will have a special length value of 1.
112.Sh RETURN VALUES
113Function
114.Fn dwarf_get_abbrev
115returns
116.Dv DW_DLV_OK
117when it succeeds.
118It returns
119.Dv DW_DLV_NO_ENTRY
120if there is no abbreviation information at offset
121.Ar offset .
122In case of an error, it returns
123.Dv DW_DLV_ERROR
124and sets the argument
125.Ar err .
126.Sh EXAMPLES
127To loop through all the abbreviation information associated with
128a DWARF debug context, use:
129.Bd -literal -offset indent
130Dwarf_Debug dbg;
131Dwarf_Abbrev ab;
132Dwarf_Off aboff;
133Dwarf_Unsigned length, attr_count;
134Dwarf_Half tag;
135Dwarf_Error de;
136int ret;
137
138while ((ret = dwarf_next_cu_header(dbg, NULL, NULL, &aboff,
139    NULL, NULL, &de)) ==  DW_DLV_OK) {
140	while ((ret = dwarf_get_abbrev(re->dbg, aboff, &ab, &length,
141	    &attr_count, &de)) == DW_DLV_OK) {
142		if (length == 1)	/* Last entry. */
143			break;
144		aboff += length;
145		if (dwarf_get_abbrev_tag(ab, &tag, &de) != DW_DLV_OK) {
146			warnx("dwarf_get_abbrev_tag failed: %s",
147			    dwarf_errmsg(de));
148			continue;
149		}
150	if (ret != DW_DLV_OK)
151		warnx("dwarf_get_abbrev: %s", dwarf_errmsg(de));
152}
153if (ret == DW_DLV_ERROR)
154	warnx("dwarf_next_cu_header: %s", dwarf_errmsg(de));
155.Ed
156.Sh ERRORS
157Function
158.Fn dwarf_get_abbrev
159can fail with:
160.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY"
161.It Bq Er DW_DLE_ARGUMENT
162One of the arguments
163.Ar dbg ,
164.Ar ret_abbrev ,
165.Ar length
166or
167.Ar attr_count
168was NULL.
169.It Bq Er DW_DLE_NO_ENTRY
170There is no abbreviation information at offset
171.Ar offset .
172.El
173.Sh SEE ALSO
174.Xr dwarf 3 ,
175.Xr dwarf_dealloc 3 ,
176.Xr dwarf_get_abbrev_children_flag 3 ,
177.Xr dwarf_get_abbrev_code 3 ,
178.Xr dwarf_get_abbrev_entry 3 ,
179.Xr dwarf_get_abbrev_tag 3
180