1.\" $NetBSD: dwarf_get_macro_details.3,v 1.2 2014/03/09 16:58:04 christos Exp $ 2.\" 3.\" Copyright (c) 2011 Kai Wang 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.\" Id: dwarf_get_macro_details.3 2071 2011-10-27 03:20:00Z jkoshy 28.\" 29.Dd March 20, 2011 30.Os 31.Dt DWARF_GET_MACRO_DETAILS 3 32.Sh NAME 33.Nm dwarf_get_macro_details 34.Nd retrieve macro information 35.Sh LIBRARY 36.Lb libdwarf 37.Sh SYNOPSIS 38.In libdwarf.h 39.Ft int 40.Fo dwarf_get_macro_details 41.Fa "Dwarf_Debug dbg" 42.Fa "Dwarf_Off offset" 43.Fa "Dwarf_Unsigned max_count" 44.Fa "Dwarf_Signed *entry_cnt" 45.Fa "Dwarf_Macro_Details **details" 46.Fa "Dwarf_Error *err" 47.Fc 48.Sh DESCRIPTION 49Function 50.Fn dwarf_get_macro_details 51retrieves information about macros associated with a DWARF debug 52context. 53Information about macro entries are returned as an array of 54descriptors of type 55.Vt Dwarf_Macro_Details , 56with each 57.Vt Dwarf_Macro_Details 58descriptor describing one macro information entry. 59.Pp 60Argument 61.Ar dbg 62should reference a DWARF debug context allocated using 63.Xr dwarf_init 3 . 64Argument 65.Ar offset 66is an offset, relative to the 67.Dq ".debug_macinfo" 68section, to the start of the desired macro information. 69Argument 70.Ar max_count 71specifies the maximum number of macro information entries 72to be returned, or 0 if all entries are to be returned. 73Argument 74.Ar entry_cnt 75should point to a location that will be set to the number 76of entries actually returned. 77Argument 78.Ar details 79should point to a location that will be set to a pointer to 80an array of 81.Vt Dwarf_Macro_Details 82descriptors. 83If argument 84.Ar err 85is not NULL, it will be used to store error information in case 86of an error. 87.Pp 88.Vt Dwarf_Macro_Details 89descriptors are defined in the header file 90.In libdwarf.h , 91and consist of the following fields: 92.Bl -tag -width ".Va dmd_fileindex" -compact 93.It Va dmd_offset 94The section-relative offset within the 95.Dq ".debug_macinfo" 96section of the macro information entry being described. 97.It Va dmd_type 98The type code of this macro information entry; one of the 99.Dv DW_MACINFO_* 100constants defined by the DWARF specification. 101.It Va dmd_lineno 102The line number associated with the macro information 103entry, or 0 if there is no applicable line number. 104.It Va dmd_fileindex 105The source file index for the macro information entry. 106This field is only meaningful when 107.Va dmd_type 108field is set to 109.Dv DW_MACINFO_start_file . 110.It Va dmd_macro 111The contents of this field is a pointer to a NUL-terminated string 112whose meaning depends on the value of the 113.Va dmd_type 114field: 115.Bl -tag -width ".Dv DW_MACINFO_vendor_ext" -compact 116.It Dv DW_MACINFO_define 117The returned string contains the macro name and value. 118.It Dv DW_MACINFO_undef 119The string holds the macro name. 120.It Dv DW_MACINFO_vendor_ext 121The 122.Va dmd_macro 123field points to a vendor defined string. 124.El 125The field is NULL for other values of 126.Va dmd_type . 127.El 128.Ss Memory Management 129The memory area used for the array of 130.Vt Dwarf_Macro_Details 131descriptors returned in argument 132.Ar details 133is owned by the 134.Lb libdwarf . 135The application should not attempt to directly free this pointer. 136Portable code should instead use 137.Fn dwarf_dealloc 138with the allocation type 139.Dv DW_DLA_STRING 140to indicate that the memory may be freed. 141.Sh RETURN VALUES 142Function 143.Fn dwarf_get_macro_details 144returns 145.Dv DW_DLV_OK 146when it succeeds. 147It returns 148.Dv DW_DLV_NO_ENTRY 149if there is no more macro information at the specified offset 150.Ar offset . 151In case of an error, it returns 152.Dv DW_DLV_ERROR 153and sets the argument 154.Ar err . 155.Sh ERRORS 156Function 157.Fn dwarf_get_macro_details 158can fail with: 159.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" 160.It Bq Er DW_DLE_ARGUMENT 161One of the arguments 162.Ar dbg , 163.Ar entry_cnt 164or 165.Ar details 166was NULL. 167.It Bq Er DW_DLE_NO_ENTRY 168There is no more macro information at the specified offset 169.Ar offset . 170.El 171.Sh EXAMPLE 172To loop through all the macro information entries associated with 173a DWARF debug context: 174.Bd -literal -offset indent 175Dwarf_Debug dbg; 176Dwarf_Unsigned offset; 177Dwarf_Signed cnt; 178Dwarf_Macro_Details *md; 179Dwarf_Error de; 180 181offset = 0; 182while (dwarf_get_macro_details(dbg, offset, 0, 183 &cnt, &md, &de) == DW_DLV_OK) { 184 for (i = 0; i < cnt; i++) { 185 /* Access fields of md[i] ... */ 186 } 187 offset = md[cnt - 1].dmd_offset + 1; 188} 189.Ed 190.Sh SEE ALSO 191.Xr dwarf 3 , 192.Xr dwarf_dealloc 3 , 193.Xr dwarf_find_macro_value_start 3 , 194.Xr dwarf_init 3 195