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_macro_details.3 2071 2011-10-27 03:20:00Z jkoshy $ 26.\" 27.Dd March 20, 2011 28.Os 29.Dt DWARF_GET_MACRO_DETAILS 3 30.Sh NAME 31.Nm dwarf_get_macro_details 32.Nd retrieve macro information 33.Sh LIBRARY 34.Lb libdwarf 35.Sh SYNOPSIS 36.In libdwarf.h 37.Ft int 38.Fo dwarf_get_macro_details 39.Fa "Dwarf_Debug dbg" 40.Fa "Dwarf_Off offset" 41.Fa "Dwarf_Unsigned max_count" 42.Fa "Dwarf_Signed *entry_cnt" 43.Fa "Dwarf_Macro_Details **details" 44.Fa "Dwarf_Error *err" 45.Fc 46.Sh DESCRIPTION 47Function 48.Fn dwarf_get_macro_details 49retrieves information about macros associated with a DWARF debug 50context. 51Information about macro entries are returned as an array of 52descriptors of type 53.Vt Dwarf_Macro_Details , 54with each 55.Vt Dwarf_Macro_Details 56descriptor describing one macro information entry. 57.Pp 58Argument 59.Ar dbg 60should reference a DWARF debug context allocated using 61.Xr dwarf_init 3 . 62Argument 63.Ar offset 64is an offset, relative to the 65.Dq ".debug_macinfo" 66section, to the start of the desired macro information. 67Argument 68.Ar max_count 69specifies the maximum number of macro information entries 70to be returned, or 0 if all entries are to be returned. 71Argument 72.Ar entry_cnt 73should point to a location that will be set to the number 74of entries actually returned. 75Argument 76.Ar details 77should point to a location that will be set to a pointer to 78an array of 79.Vt Dwarf_Macro_Details 80descriptors. 81If argument 82.Ar err 83is not NULL, it will be used to store error information in case 84of an error. 85.Pp 86.Vt Dwarf_Macro_Details 87descriptors are defined in the header file 88.In libdwarf.h , 89and consist of the following fields: 90.Bl -tag -width ".Va dmd_fileindex" -compact 91.It Va dmd_offset 92The section-relative offset within the 93.Dq ".debug_macinfo" 94section of the macro information entry being described. 95.It Va dmd_type 96The type code of this macro information entry; one of the 97.Dv DW_MACINFO_* 98constants defined by the DWARF specification. 99.It Va dmd_lineno 100The line number associated with the macro information 101entry, or 0 if there is no applicable line number. 102.It Va dmd_fileindex 103The source file index for the macro information entry. 104This field is only meaningful when 105.Va dmd_type 106field is set to 107.Dv DW_MACINFO_start_file . 108.It Va dmd_macro 109The contents of this field is a pointer to a NUL-terminated string 110whose meaning depends on the value of the 111.Va dmd_type 112field: 113.Bl -tag -width ".Dv DW_MACINFO_vendor_ext" -compact 114.It Dv DW_MACINFO_define 115The returned string contains the macro name and value. 116.It Dv DW_MACINFO_undef 117The string holds the macro name. 118.It Dv DW_MACINFO_vendor_ext 119The 120.Va dmd_macro 121field points to a vendor defined string. 122.El 123The field is NULL for other values of 124.Va dmd_type . 125.El 126.Ss Memory Management 127The memory area used for the array of 128.Vt Dwarf_Macro_Details 129descriptors returned in argument 130.Ar details 131is owned by the 132.Lb libdwarf . 133The application should not attempt to directly free this pointer. 134Portable code should instead use 135.Fn dwarf_dealloc 136with the allocation type 137.Dv DW_DLA_STRING 138to indicate that the memory may be freed. 139.Sh RETURN VALUES 140Function 141.Fn dwarf_get_macro_details 142returns 143.Dv DW_DLV_OK 144when it succeeds. 145It returns 146.Dv DW_DLV_NO_ENTRY 147if there is no more macro information at the specified offset 148.Ar offset . 149In case of an error, it returns 150.Dv DW_DLV_ERROR 151and sets the argument 152.Ar err . 153.Sh ERRORS 154Function 155.Fn dwarf_get_macro_details 156can fail with: 157.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" 158.It Bq Er DW_DLE_ARGUMENT 159One of the arguments 160.Ar dbg , 161.Ar entry_cnt 162or 163.Ar details 164was NULL. 165.It Bq Er DW_DLE_NO_ENTRY 166There is no more macro information at the specified offset 167.Ar offset . 168.El 169.Sh EXAMPLE 170To loop through all the macro information entries associated with 171a DWARF debug context: 172.Bd -literal -offset indent 173Dwarf_Debug dbg; 174Dwarf_Unsigned offset; 175Dwarf_Signed cnt; 176Dwarf_Macro_Details *md; 177Dwarf_Error de; 178 179offset = 0; 180while (dwarf_get_macro_details(dbg, offset, 0, 181 &cnt, &md, &de) == DW_DLV_OK) { 182 for (i = 0; i < cnt; i++) { 183 /* Access fields of md[i] ... */ 184 } 185 offset = md[cnt - 1].dmd_offset + 1; 186} 187.Ed 188.Sh SEE ALSO 189.Xr dwarf 3 , 190.Xr dwarf_dealloc 3 , 191.Xr dwarf_find_macro_value_start 3 , 192.Xr dwarf_init 3 193