contrib/elftoolchain/libdwarf/dwarf_get_macro_details.3

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