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