1 .\" Copyright (c) 2011 Kai Wang
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
25 .\" $Id: dwarf_producer_init.3 2074 2011-10-27 03:34:33Z jkoshy $
29 .Dt DWARF_PRODUCER_INIT 3
31 .Nm dwarf_producer_init
32 .Nm dwarf_producer_init_b
33 .Nd allocate a DWARF producer descriptor
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"
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"
55 These functions allocate and return a
57 descriptor representing a DWARF producer instance.
61 should contain the adddress of a function to be called in case of an
65 the default error handling scheme is used, see
70 will be passed to the error handler function when it is invoked.
74 references a memory location that would hold a
76 descriptor in case of an error.
80 specifies additional characteristics of the DWARF producer instance.
81 The following flags are recognized:
83 .Bl -tag -width "Dv DW_DLC_ISA_MIPS"
84 .It Dv DW_DLC_ISA_IA64
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
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.
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
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.
114 Permit writing of DWARF information.
117 The following flags are mutually exclusive.
123 .Dv DW_DLC_ISA_MIPS .
131 .Dv DW_DLC_STREAM_RELOCATIONS
133 .Dv DW_DLC_SYMBOLIC_RELOCATIONS .
136 .Dv DW_DLC_TARGET_BIGENDIAN
138 .Dv DW_DLC_TARGET_LITTLEENDIAN .
140 If neither of the flags
141 .Dv DW_DLC_TARGET_BIGENDIAN
143 .Dv DW_DLC_TARGET_LITTLEENDIAN
144 is set, the target's endianness is assumed to be the same as the host's
149 should point to an application-provided callback function of type
150 .Vt Dwarf_Callback_Func_b .
152 .Vt Dwarf_Callback_Func_b
153 is defined in the header file
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);
162 This function is called by the
164 once for each section in the object file that the library needs to
166 The arguments to this callback function specify the values in the ELF
167 section header for the section being created:
169 .Bl -tag -width indent -compact -offset indent
171 The name of the section being created.
175 value in the section header.
179 value in the section header.
183 value in the section header.
187 value in the section header.
191 value in the section header.
194 On success, the callback function should return the section index
195 value of the created section, and set the location pointed to by
198 to the symbol table index of the symbol that associated with the newly
200 This symbol table index will be used in relocation entries
201 referring to the created section.
203 In case of failure, the callback function should return -1 and set the
204 location pointed to by argument
206 to an application-defined error code.
207 This application returned error code is currently ignored by the
211 .Fn dwarf_producer_init
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
222 instance returned by these functions should be freed using the
224 .Fn dwarf_producer_finish .
226 On success, these functions return the created DWARF producer
228 In case of an error, they return
233 These functions can fail with:
234 .Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY"
235 .It Bq Er DW_DLE_ARGUMENT
239 .It Bq Er DW_DLE_ARGUMENT
242 was not set in argument
244 .It Bq Er DW_DLE_ARGUMENT
249 were both set in argument
251 .It Bq Er DW_DLE_ARGUMENT
256 were both set in argument
258 .It Bq Er DW_DLE_ARGUMENT
260 .Dv DW_DLC_TARGET_BIGENDIAN
262 .Dv DW_DLC_TARGET_LITTLEENDIAN
263 were both set in argument
265 .It Bq Er DW_DLE_ARGUMENT
267 .Dv DW_DLC_STREAM_RELOCATIONS
269 .Dv DW_DLC_SYMBOLIC_RELOCATIONS
270 were both set in argument
272 .It Bq Er DW_DLE_MEMORY
273 An out of memory condition was encountered.
278 instance for a MIPS32 big endian object, use:
279 .Bd -literal -offset indent
281 Dwarf_Unsigned flags;
284 /* ... assume cb_func points to the callback function ... */
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)) ==
290 warnx("dwarf_producer_init failed: %s", dwarf_errmsg(-1));
295 .Xr dwarf_producer_finish 3 ,
296 .Xr dwarf_producer_set_isa 3 ,
297 .Xr dwarf_transform_to_disk_form 3