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 3644 2018-10-15 19:55:01Z jkoshy $ 26.\" 27.Dd November 9, 2011 28.Dt DWARF_ATTRLIST 3 29.Os 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 86on success. 87.Pp 88If the debugging information entry descriptor denoted by argument 89.Ar die 90does not contain any attribute, the function returns 91.Dv DW_DLV_NO_ENTRY 92and sets argument 93.Ar err . 94For other errors, it returns 95.Dv DW_DLV_ERROR 96and sets argument 97.Ar err . 98.Sh EXAMPLES 99To retrieve the attribute list for a DWARF debugging information 100entry use: 101.Bd -literal -offset indent 102Dwarf_Die dw_die; 103Dwarf_Error dw_e; 104Dwarf_Unsigned dw_count; 105Dwarf_Attribute *dw_attributes; 106int error, i; 107 108\&... variable dw_die contains a reference to the DIE of interest ... 109 110/* Retrieve the attribute list from the DIE. */ 111if ((error = dwarf_attrlist(dw_die, &dw_attributes, &dw_count, 112 &dw_e)) != DW_DLV_OK) 113 errx(EXIT_FAILURE, "dwarf_attrlist: %s", dwarf_errmsg(dw_e)); 114 115/* Process the attribute list. */ 116for (i = 0; i < dw_count; ++i) { 117 /* Use the returned pointers in dw_attributes[i] here. */ 118} 119.Ed 120.Sh ERRORS 121Function 122.Fn dwarf_diename 123can fail with the following errors: 124.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" 125.It Bq Er DW_DLE_ARGUMENT 126Arguments 127.Ar die , 128.Ar attrbuf , 129or 130.Ar attrcount 131were NULL. 132.It Bq Er DW_DLE_NO_ENTRY 133Argument 134.Ar die 135had no attributes. 136.It Bq Er DW_DLE_MEMORY 137An out of memory condition was encountered during the execution of the 138function. 139.El 140.Sh SEE ALSO 141.Xr dwarf 3 , 142.Xr dwarf_attr 3 , 143.Xr dwarf_dealloc 3 , 144.Xr dwarf_hasattr 3 , 145.Xr dwarf_hasform 3 , 146.Xr dwarf_whatattr 3 , 147.Xr dwarf_whatform 3 148