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