contrib/elftoolchain/libdwarf/dwarf_producer_init.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_producer_init.3 3644 2018-10-15 19:55:01Z jkoshy $
  26 .\"
  27 .Dd August 20, 2011
  28 .Dt DWARF_PRODUCER_INIT 3
  29 .Os
  30 .Sh NAME
  31 .Nm dwarf_producer_init ,
  32 .Nm dwarf_producer_init_b
  33 .Nd allocate a DWARF producer descriptor
  34 .Sh LIBRARY
  35 .Lb libdwarf
  36 .Sh SYNOPSIS
  37 .In libdwarf.h
  38 .Ft Dwarf_P_Debug
  39 .Fo dwarf_producer_init
  40 .Fa "Dwarf_Unsigned flags"
  41 .Fa "Dwarf_Callback_Func func"
  42 .Fa "Dwarf_Handler errhand"
  43 .Fa "Dwarf_Ptr errarg"
  44 .Fa "Dwarf_Error *err"
  45 .Fc
  46 .Ft Dwarf_P_Debug
  47 .Fo dwarf_producer_init_b
  48 .Fa "Dwarf_Unsigned flags"
  49 .Fa "Dwarf_Callback_Func_b func"
  50 .Fa "Dwarf_Handler errhand"
  51 .Fa "Dwarf_Ptr errarg"
  52 .Fa "Dwarf_Error *error"
  53 .Fc
  54 .Sh DESCRIPTION
  55 These functions allocate and return a
  56 .Vt Dwarf_P_Debug
  57 descriptor representing a DWARF producer instance.
  58 .Pp
  59 The argument
  60 .Ar errhand
  61 should contain the address of a function to be called in case of an
  62 error.
  63 If this argument is
  64 .Dv NULL ,
  65 the default error handling scheme is used, see
  66 .Xr dwarf 3 .
  67 .Pp
  68 The argument
  69 .Ar errarg
  70 will be passed to the error handler function when it is invoked.
  71 .Pp
  72 The argument
  73 .Ar err
  74 references a memory location that would hold a
  75 .Vt Dwarf_Error
  76 descriptor in case of an error.
  77 .Pp
  78 The argument
  79 .Ar flags
  80 specifies additional characteristics of the DWARF producer instance.
  81 The following flags are recognized:
  82 .Bl -tag -width "Dv DW_DLC_ISA_MIPS"
  83 .It Dv DW_DLC_ISA_IA64
  84 .Pq Deprecated
  85 The target instruction set architecture is IA64.
  86 This flag is deprecated.
  87 Application code should use the
  88 .Xr dwarf_producer_set_isa 3
  89 function to specify target instruction set architecture.
  90 .It Dv DW_DLC_ISA_MIPS
  91 .Pq Deprecated
  92 The target instruction set architecture is MIPS.
  93 This flag is deprecated.
  94 Application code should use the
  95 .Xr dwarf_producer_set_isa 3
  96 function to specify target instruction set architecture.
  97 .It Dv DW_DLC_SIZE_32
  98 .Pq Default
  99 The target address size is 32-bit.
 100 .It Dv DW_DLC_SIZE_64
 101 The target address size is 64-bit.
 102 .It Dv DW_DLC_STREAM_RELOCATIONS
 103 .Pq Default
 104 Generate stream relocations.
 105 .It Dv DW_DLC_SYMBOLIC_RELOCATIONS
 106 Generate symbolic relocations.
 107 .It Dv DW_DLC_TARGET_BIGENDIAN
 108 The target is big endian.
 109 .It Dv DW_DLC_TARGET_LITTLEENDIAN
 110 The target is little endian.
 111 .It Dv DW_DLC_WRITE
 112 .Pq Required
 113 Permit writing of DWARF information.
 114 .El
 115 .Pp
 116 The following flags are mutually exclusive.
 117 .Bl -bullet -compact
 118 .It
 119 Flags
 120 .Dv DW_DLC_ISA_IA64
 121 and
 122 .Dv DW_DLC_ISA_MIPS .
 123 .It
 124 Flags
 125 .Dv DW_DLC_SIZE_32
 126 and
 127 .Dv DW_DLC_SIZE_64 .
 128 .It
 129 Flags
 130 .Dv DW_DLC_STREAM_RELOCATIONS
 131 and
 132 .Dv DW_DLC_SYMBOLIC_RELOCATIONS .
 133 .It
 134 Flags
 135 .Dv DW_DLC_TARGET_BIGENDIAN
 136 and
 137 .Dv DW_DLC_TARGET_LITTLEENDIAN .
 138 .El
 139 If neither of the flags
 140 .Dv DW_DLC_TARGET_BIGENDIAN
 141 and
 142 .Dv DW_DLC_TARGET_LITTLEENDIAN
 143 is set, the target's endianness is assumed to be the same as the host's
 144 endianness.
 145 .Pp
 146 Argument
 147 .Ar func
 148 should point to an application-provided callback function of type
 149 .Vt Dwarf_Callback_Func_b .
 150 The type
 151 .Vt Dwarf_Callback_Func_b
 152 is defined in the header file
 153 .In libdwarf.h
 154 as:
 155 .Bd -literal -offset indent
 156 typedef int (*Dwarf_Callback_Func_b)(char *name, int size,
 157     Dwarf_Unsigned type, Dwarf_Unsigned flags, Dwarf_Unsigned link,
 158     Dwarf_Unsigned info, Dwarf_Unsigned *index, int *error);
 159 .Ed
 160 .Pp
 161 This function is called by the
 162 .Lb libdwarf
 163 once for each section in the object file that the library needs to
 164 create.
 165 The arguments to this callback function specify the values in the ELF
 166 section header for the section being created:
 167 .Pp
 168 .Bl -tag -width indent -compact -offset indent
 169 .It Ar name
 170 The name of the section being created.
 171 .It Ar size
 172 The
 173 .Va sh_size
 174 value in the section header.
 175 .It Ar type
 176 The
 177 .Va sh_type
 178 value in the section header.
 179 .It Ar flags
 180 The
 181 .Va sh_flags
 182 value in the section header.
 183 .It Ar link
 184 The
 185 .Va sh_link
 186 value in the section header.
 187 .It Ar info
 188 The
 189 .Va sh_info
 190 value in the section header.
 191 .El
 192 .Pp
 193 On success, the callback function should return the section index
 194 value of the created section, and set the location pointed to by
 195 argument
 196 .Ar index
 197 to the symbol table index of the symbol that associated with the newly
 198 created section.
 199 This symbol table index will be used in relocation entries
 200 referring to the created section.
 201 .Pp
 202 In case of failure, the callback function should return -1 and set the
 203 location pointed to by argument
 204 .Ar error
 205 to an application-defined error code.
 206 This application returned error code is currently ignored by the
 207 library.
 208 .Pp
 209 Function
 210 .Fn dwarf_producer_init
 211 is deprecated.
 212 Function
 213 .Fn dwarf_producer_init
 214 is identical to function
 215 .Fn dwarf_producer_init_b
 216 except that the callback function it expects can not properly handle
 217 arbitrary section symbol index values.
 218 .Ss Memory Management
 219 The
 220 .Vt Dwarf_P_Debug
 221 instance returned by these functions should be freed using the
 222 function
 223 .Fn dwarf_producer_finish .
 224 .Sh RETURN VALUES
 225 On success, these functions return the created DWARF producer
 226 descriptor.
 227 In case of an error, they return
 228 .Dv DW_DLV_BADADDR
 229 and set the argument
 230 .Ar err .
 231 .Sh EXAMPLES
 232 To initialize a
 233 .Vt Dwarf_P_Debug
 234 instance for a MIPS32 big endian object, use:
 235 .Bd -literal -offset indent
 236 Dwarf_P_Debug dbg;
 237 Dwarf_Unsigned flags;
 238 Dwarf_Error de;
 239
 240 /* ... assume cb_func points to the callback function ... */
 241
 242 flags = DW_DLC_WRITE | DW_DLC_SIZE_32 | DW_DLC_ISA_MIPS |
 243     DW_DLC_STREAM_RELOCATIONS | DW_DLC_TARGET_BIGENDIAN;
 244 if ((dbg = dwarf_producer_init(flags, cb_func, NULL, NULL, &de)) ==
 245     DW_DLV_BADADDR)
 246         warnx("dwarf_producer_init failed: %s", dwarf_errmsg(-1));
 247 .Ed
 248 .Sh ERRORS
 249 These functions can fail with:
 250 .Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY"
 251 .It Bq Er DW_DLE_ARGUMENT
 252 Argument
 253 .Ar func
 254 was NULL.
 255 .It Bq Er DW_DLE_ARGUMENT
 256 The flag
 257 .Dv DW_DLC_WRITE
 258 was not set in argument
 259 .Ar flags .
 260 .It Bq Er DW_DLE_ARGUMENT
 261 The flags
 262 .Dv DW_DLC_SIZE_32
 263 and
 264 .Dv DW_DLC_SIZE_64
 265 were both set in argument
 266 .Ar flags .
 267 .It Bq Er DW_DLE_ARGUMENT
 268 The flags
 269 .Dv DW_DLC_ISA_IA64
 270 and
 271 .Dv DW_DLC_ISA_MIPS
 272 were both set in argument
 273 .Ar flags .
 274 .It Bq Er DW_DLE_ARGUMENT
 275 The flags
 276 .Dv DW_DLC_TARGET_BIGENDIAN
 277 and
 278 .Dv DW_DLC_TARGET_LITTLEENDIAN
 279 were both set in argument
 280 .Ar flags .
 281 .It Bq Er DW_DLE_ARGUMENT
 282 The flags
 283 .Dv DW_DLC_STREAM_RELOCATIONS
 284 and
 285 .Dv DW_DLC_SYMBOLIC_RELOCATIONS
 286 were both set in argument
 287 .Ar flags .
 288 .It Bq Er DW_DLE_MEMORY
 289 An out of memory condition was encountered.
 290 .El
 291 .Sh SEE ALSO
 292 .Xr dwarf 3 ,
 293 .Xr dwarf_errmsg 3 ,
 294 .Xr dwarf_producer_finish 3 ,
 295 .Xr dwarf_producer_set_isa 3 ,
 296 .Xr dwarf_transform_to_disk_form 3