1.\" Copyright (c) 2010 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_attrlist.3 2122 2011-11-09 15:35:14Z jkoshy $ 26.\" 27.Dd November 9, 2011 28.Os 29.Dt DWARF_ATTRLIST 3 30.Sh NAME 31.Nm dwarf_attrlist 32.Nd retrieve DWARF attribute descriptors 33.Sh LIBRARY 34.Lb libdwarf 35.Sh SYNOPSIS 36.In libdwarf.h 37.Ft int 38.Fo dwarf_attrlist 39.Fa "Dwarf_Die die" 40.Fa "Dwarf_Attribute **attrbuf" 41.Fa "Dwarf_Signed *attrcount" 42.Fa "Dwarf_Error *err" 43.Fc 44.Sh DESCRIPTION 45Function 46.Fn dwarf_attrlist 47retrieves the DWARF attribute descriptors associated with a 48debugging information entry descriptor in argument 49.Ar die . 50The descriptors are returned as an array of values of the opaque type 51.Vt Dwarf_Attribute . 52The data associated with each returned attribute descriptor may be 53queried using the form query functions in the 54.Xr dwarf 3 55API set. 56.Pp 57Argument 58.Ar attrbuf 59points to a location that will hold a pointer to the returned 60array of DWARF attribute descriptors. 61Argument 62.Ar attrcount 63points to a location that will hold the number of descriptors in 64the returned array. 65.Pp 66If argument 67.Ar err 68is non-NULL, it is used to return an error descriptor in case of an 69error. 70.Ss Memory Management 71In the current implementation, the memory allocated for each DWARF 72attribute descriptor and for the returned array of descriptors is 73managed by the library and the application does not need to explicitly 74free the returned pointers. 75However, for compatibility with other implementations of the 76.Xr dwarf 3 77API, the application is permitted to pass the pointers returned by to 78the 79.Fn dwarf_dealloc 80function. 81.Sh RETURN VALUES 82Function 83.Fn dwarf_attrlist 84returns 85.Dv DW_DLV_OK on success. 86.Pp 87If the debugging information entry descriptor denoted by argument 88.Ar die 89does not contain any attribute, the function returns 90.Dv DW_DLV_NO_ENTRY 91and sets argument 92.Ar err . 93For other errors, it returns 94.Dv DW_DLV_ERROR 95and sets argument 96.Ar err . 97.Sh EXAMPLES 98To retrieve the attribute list for a DWARF debugging information 99entry use: 100.Bd -literal -offset indent 101Dwarf_Die dw_die; 102Dwarf_Error dw_e; 103Dwarf_Unsigned dw_count; 104Dwarf_Attribute *dw_attributes; 105int error, i; 106 107\&... variable dw_die contains a reference to the DIE of interest ... 108 109/* Retrieve the attribute list from the DIE. */ 110if ((error = dwarf_attrlist(dw_die, &dw_attributes, &dw_count, 111 &dw_e)) != DW_DLV_OK) 112 errx(EXIT_FAILURE, "dwarf_attrlist: %s", dwarf_errmsg(dw_e)); 113 114/* Process the attribute list. */ 115for (i = 0; i < dw_count; ++i) { 116 /* Use the returned pointers in dw_attributes[i] here. */ 117} 118.Ed 119.Sh ERRORS 120Function 121.Fn dwarf_diename 122can fail with the following errors: 123.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" 124.It Bq Er DW_DLE_ARGUMENT 125Arguments 126.Ar die , 127.Ar attrbuf , 128or 129.Ar attrcount 130were NULL. 131.It Bq Er DW_DLE_NO_ENTRY 132Argument 133.Ar die 134had no attributes. 135.It Bq Er DW_DLE_MEMORY 136An out of memory condition was encountered during the execution of the 137function. 138.El 139.Sh SEE ALSO 140.Xr dwarf 3 , 141.Xr dwarf_attr 3 , 142.Xr dwarf_dealloc 3 , 143.Xr dwarf_hasattr 3 , 144.Xr dwarf_hasform 3 , 145.Xr dwarf_whatattr 3 , 146.Xr dwarf_whatform 3 147